home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / tpmagic.zip / MAGIC.DOC < prev    next >
Text File  |  1992-01-18  |  132KB  |  3,189 lines

  1.  
  2.  
  3.                                  PASCAL MAGIC
  4.  
  5.                                   Magic Unit
  6.  
  7.                                 Reference File
  8.  
  9.  
  10.                     An Add-in For Turbo Pascal, Version 6.0
  11.  
  12.                  Copyright 1991, Jeff Napier & Another Company
  13.  
  14.  
  15.          What Magic will do for you:
  16.  
  17.          *   Make  professional  multi-color,  shadowed  pop-up  help,
  18.          warnings, dialog,  general  text  boxes  and  lightbar  menus
  19.          instantly without wasting your time 're-inventing the wheel'.
  20.  
  21.          * Incorporate .BGI graphics drivers and .CHR fonts into  your
  22.          .EXE programs by typing a single word!
  23.  
  24.          * Gain mouse support without writing a mouse driver.
  25.  
  26.          * Gain color control without writing color control code.
  27.  
  28.          * Many Turbo Pascal procedures greatly simplified.
  29.  
  30.          * Write graphics-based programs as easily as text-based.
  31.  
  32.          * Disk file handling is done automatically.
  33.  
  34.          * Enlarged cursor available for your programs  for  use  with
  35.            laptop LCD displays.
  36.  
  37.          * Add sound effects to your program effortlessly.
  38.  
  39.  
  40.          Notice: This is shareware. Feel free to copy  and  distribute
  41.          without  modification.   If  you use any portion of the Magic
  42.          Unit in your programs then registration is a legal necessity.
  43.          Send $29.95 to Another  Company.   Complete,  well-documented
  44.          easy-to-understand source code is available. For registration
  45.          + registration, send $59.90.
  46.  
  47.          Send US funds drawn on a US bank to:
  48.  
  49.                                 Another Company
  50.                                  P.O. Box 298
  51.                               Applegate, OR 97530
  52.                                       USA
  53.                                  503-846-7884
  54.  
  55.          Even  though  this  seems quite bug-free to me, it is version
  56.          1.0 and you may find a surprise or two. I make  no  warranty.
  57.          Please  feel  free  to  submit bug reports, and I will try to
  58.          incorporate appropriate fixes.
  59.  
  60.          (If  you  are  new  to  Pascal,  or  if  you  would  like   a
  61.          step-by-step guide, you are looking at the wrong file. Please
  62.          see Tutorial.txt first.)
  63.  
  64.          Note: Fonts.tpu, Video.tpu, and Borland's Graph.tpu  must  be
  65.          in the same sub-directory in which you keep your tpu files.
  66.  
  67.  
  68.                        ALPHABETICALLY ARRANGED REFERENCE
  69.                   TO ALL THE FEATURES AVAILABLE IN MAGIC UNIT
  70.  
  71.          NOTE:  All  procedures,  functions  and global variables work
  72.          identically in text and all graphics modes  unless  otherwise
  73.          stated.
  74.  
  75.          *************************************************************
  76.          Answer - Global Variable                           Uses Magic
  77.  
  78.          Declaration: (example) teststring := answer
  79.  
  80.          Description:
  81.             Answer  is  a  string  which  is returned by the procedure
  82.          Dialog. You can also use answer as a general  purpose  global
  83.          string variable.
  84.  
  85.          Considerations:
  86.             Maximum size of answer is 76 characters.
  87.  
  88.          See also: Dialog
  89.  
  90.          Example:
  91.          program test;
  92.          uses agic;
  93.          begin
  94.             sent[1] := 'Write your answer here';
  95.             dialog(1,1);
  96.             if copy(answer,1,2) = 'I ' then User_Started_With_I;
  97.             .
  98.             .
  99.          end.
  100.  
  101.          Performance of example:
  102.          A dialog box pops up and the user types an answer. The string
  103.          typed by the user is contained in the string, answer. A  test
  104.          is made to see if the first two characters of answer are 'I '
  105.          and  if  so,  an  imaginary procedure, User_Started_With_I is
  106.          called.
  107.  
  108.          *************************************************************
  109.          BarBack - Global Variable                          Uses Magic
  110.  
  111.          Declaration: BarBack := color
  112.  
  113.          Description:
  114.          This  sets  the  background color for lightbar backgrounds in
  115.          menus, where 'color' is an integer from 0 to 7,  in  graphics
  116.          mode  or 0 to 15 in text mode, or a color constant as defined
  117.          by Borland. The colors 0 - 7 are the same in  both  text  and
  118.          graphics modes.
  119.  
  120.          Considerations:
  121.          May  not  have the expected effect when used with the limited
  122.          palettes of 4-color CGA (mode  0,1  or  2),  2-color  CGA  or
  123.          Hercules.
  124.  
  125.          See also: BarText, BoxBack, BoxText
  126.  
  127.          Example:
  128.          program test;
  129.          uses magic;
  130.          begin
  131.             sent[1] := 'First Thing';
  132.             sent[2] := 'Second Thing';
  133.             sent[3] := 'Quit';
  134.             mc := 1;
  135.             BarBack := Red;
  136.             menu(-1,-1);
  137.             .
  138.             .
  139.          end.
  140.  
  141.          Performance of example:
  142.          Three  strings  are  declared.  The  menu  bar  will start by
  143.          highlighting sent[1] when the menu is displayed.  Because  of
  144.          the  preceding  change  to  BarBack,  the  background of the
  145.          highlighted menu item will be in red.
  146.  
  147.          *************************************************************
  148.          BarText - Global Variable                          Uses Magic
  149.  
  150.          Declaration: BarText := color
  151.  
  152.          Description:
  153.          This sets the color for lightbar text in menus, where 'color'
  154.          is an integer from 0 to 15 or a color constant as defined  by
  155.          Borland. Colors are the same in graphics and text modes.
  156.  
  157.          Considerations:
  158.          May  not  have the expected effect when used with the limited
  159.          palettes of 4-color CGA (mode  0,1  or  2),  2-color  CGA  or
  160.          Hercules.
  161.  
  162.          See also: BarBack, BoxBack, BoxText
  163.  
  164.          Example:
  165.          program test;
  166.          uses magic;
  167.          begin
  168.             sent[1] := 'First Thing';
  169.             sent[2] := 'Second Thing';
  170.             sent[3] := 'Quit';
  171.             mc := 1;
  172.             BarText := red;
  173.             menu(-1,-1);
  174.             .
  175.             .
  176.          end.
  177.  
  178.          Performance of example:
  179.          Three  strings  are  declared.   The  menu  bar will start by
  180.          highlighting sent[1] when the menu is displayed.  Because  of
  181.          the  preceding  change to BarText, the highlighted menu text
  182.          will be displayed in red.
  183.  
  184.          *************************************************************
  185.          BestVideo - Procedure                              Uses Magic
  186.  
  187.          Declaration:  Bestvideo
  188.  
  189.          Description:
  190.          By  simply  declaring  BESTVIDEO,  the  program  detects  the
  191.          graphics card present and switches to the best graphics  mode
  192.          possible  for  that  card.  When  the program is compiled all
  193.          video drivers (*.BGI files) are automatically built into  the
  194.          .EXE  file.  The  compiled  program will therefore run on any
  195.          standard graphics-equipped system, but will be large in size.
  196.          Video.Tpu must be available until after compilation.
  197.  
  198.          Considerations:
  199.          Must add Graph, Video, Magic to Uses statement.
  200.  
  201.          See also:
  202.          CgaVideo, EgaVideo, HercVideo, VgaVideo,  all  Borland  Graph
  203.          procedures & functions.
  204.  
  205.          Example:
  206.          program test;
  207.          uses crt,graph,video,magic;
  208.          begin
  209.             BestVideo;
  210.             line(0,0,getmaxx,getmaxy);
  211.             repeat until keypressed;
  212.             CleanUp;
  213.          end.
  214.  
  215.          Performance of example:
  216.          Initializes best graphics mode, draws a  diagonal  line  from
  217.          the  upper  left  corner  to  the  lower  right corner of the
  218.          screen,  waits  until  a  key  is  pressed,  then  terminates
  219.          gracefully.  Crt  must be in the uses line because keypressed
  220.          is a procedure within the Crt unit (Turbo.tpl).
  221.  
  222.          *************************************************************
  223.          BigCursor - Procedure                              Uses Magic
  224.  
  225.          Declaration: BigCursor
  226.  
  227.          Description:
  228.          After a call to BigCursor, the cursor in text mode will be a
  229.          block  the size of a whole character instead of an underline.
  230.          This is particularly useful  in  programs  designed  for  LCD
  231.          laptop   screens.    Unless   a  specific  call  is  made  to
  232.          SmallCursor before the end of the  program,  the  big  cursor
  233.          will remain in effect at the DOS prompt and within most other
  234.          programs.
  235.  
  236.          Considerations:
  237.             Has  no  effect  in  graphics  modes, but will resume as a
  238.          large cursor when returned to text mode.
  239.  
  240.          Example:
  241.          program test;
  242.          uses magic;
  243.          begin
  244.             BigCursor;
  245.             write('Big cursor at the end of this line!');
  246.          end.
  247.  
  248.          Performance of Example:
  249.          This program will write 'Big cursor at the end of this line',
  250.          then quit. If run from the IDE, nothing will seem to  happen,
  251.          but if compiled and run from DOS, after execution, the cursor
  252.          will become large and stay that way.
  253.  
  254.          *************************************************************
  255.          Border - Global Variable                           Uses Magic
  256.  
  257.          Declaration: border := color;
  258.  
  259.          Description:
  260.          Color  is represented with an integer  from  0  to  15  or  a
  261.          pre-defined  color  constant (Borland). Changing the value of
  262.          border will affect the color of borders drawn  around  pop-up
  263.          text  boxes,  dialog  boxes  and  menus.  Colors are the same
  264.          in text and graphics mode.
  265.  
  266.          Considerations:
  267.          May  not  have the expected effect when used with the limited
  268.          palettes of 4-color CGA (mode  0,1  or  2),  2-color  CGA  or
  269.          Hercules.
  270.  
  271.          See Also:
  272.          Shadow,  MainBack,  MainText,  Boxback,   Boxtext,   Barback,
  273.          Bartext.
  274.  
  275.          Example:
  276.          Program Test;
  277.          uses magic;
  278.          begin
  279.             border := white;
  280.             sent[1] := 'Do you like this border color?';
  281.             GetAnyKey(-1,-1);
  282.          end.
  283.  
  284.          Performance of example:
  285.          The  border  color  is set to white. A box will appear on the
  286.          screen asking a silly question. The box  will  have  a  white
  287.          border. When a key is pressed, the program quits.
  288.  
  289.          *************************************************************
  290.          Boxback - Global Variable                          Uses Magic
  291.  
  292.          Declaration: BoxBack:= color;
  293.  
  294.          Description:
  295.          Color  is represented with an integer  from  0  to  15  or  a
  296.          pre-defined  color  constant (Borland). Changing the value of
  297.          BoxBack  will  affect  the  background color of pop-up boxes,
  298.          text boxes, dialog  boxes  and  menus.
  299.  
  300.          Considerations:
  301.             Do not use background colors above 7 in text mode. May not
  302.          have the expected effect when used with the limited  palettes
  303.          of 4-color CGA (mode 0,1 or 2), 2-color CGA or Hercules.
  304.  
  305.          See Also:
  306.          MainBack, MainText, Boxtext, Barback, Bartext.
  307.  
  308.          Example:
  309.          Program Test;
  310.          uses magic;
  311.          begin
  312.             BoxBack := magenta;
  313.             sent[1] := 'Do you like this background color?';
  314.             getanykey(-1,-1);
  315.          end.
  316.  
  317.          Performance of example:
  318.          The  box  background  color  is  set  to  magenta. A box will
  319.          appear on the screen asking a silly question.  The  box  will
  320.          have  a  magenta  background.   When  a  key  is pressed, the
  321.          program quits.
  322.  
  323.          *************************************************************
  324.          BoxText - Global Variable                          Uses Magic
  325.  
  326.          Declaration: BoxBack:= color;
  327.  
  328.          Description:
  329.          Color  is represented with an integer  from  0  to  15  or  a
  330.          pre-defined color constant (Borland). Changing the  value  of
  331.          BoxText  will  affect  the  text  color in pop-up boxes, text
  332.          boxes,  dialog  boxes and menus.  Colors are the same in text
  333.          and graphics modes.
  334.  
  335.          Considerations:
  336.          May  not  have the expected effect when used with the limited
  337.          palettes of 4-color CGA (mode  0,1  or  2),  2-color  CGA  or
  338.          Hercules.
  339.  
  340.          See Also:
  341.          MainBack, MainText, Boxtext, Barback, Bartext.
  342.  
  343.          Example:
  344.          Program Test;
  345.          uses magic;
  346.          begin
  347.             BoxText := black;
  348.             sent[1] := 'Do you like this text color?';
  349.             getanykey(-1,-1);
  350.          end.
  351.  
  352.          Performance of example:
  353.          The  box text color is set to black. A box will appear on the
  354.          screen asking a silly question.  The box will  contain  black
  355.          text.
  356.  
  357.          *************************************************************
  358.          Bx, By - Global Variables                          Uses Magic
  359.  
  360.          Declaration: (example) gotoxy(bx,by)
  361.  
  362.          Description:
  363.             These are global integer  variables  used  to  locate  the
  364.          upper   left  corner  of  pop-up  boxes.  Bx  represents  the
  365.          horizontal position and By is the vertical position.
  366.             In text mode the upper left corner is  1,1  and  the  very
  367.          lower right corner would be 80,25.
  368.             In  graphics  modes,  the upper left corner is 0,0 and the
  369.          lower right varies with the current graphics mode. In VGA 640
  370.          x 480,  for  instance,  the  lower  right  corner  is  called
  371.          639,479.
  372.  
  373.          Considerations:
  374.              In  most  applications  within  the  Magic  unit,  when a
  375.          negative number is assigned to Bx or to By, that number  will
  376.          be igored or overwritten a new number,  and  the  pop-up  box
  377.          will  be  centered  on  the  screen  in  that dimension. When
  378.          overwritten, the new number becomes the center of the  screen
  379.          minus half the size of the pop-up box.
  380.  
  381.          See Also:
  382.          Pop,  GetAnyKey,  GetYN,  Dialog,  Menu,  DoubleMenu  {Magic}
  383.          GetMaxX, GetMaxY, WhereX, Wherey {Borland}
  384.  
  385.          Example:
  386.          Program Test;
  387.          uses magic;
  388.          begin
  389.             sent[1] := 'Write message below:';
  390.             dialog(-1,3);
  391.             .
  392.             .
  393.          end.
  394.  
  395.          Performance of example:
  396.          A  box  pops  up  in  the center of the screen containing one
  397.          line  of  text and a blank line in which the user can type an
  398.          answer.  The box is centered on the screen horizontally,  and
  399.          the upper edge is three rows from the top of the screen.
  400.  
  401.          *************************************************************
  402.          CenterJustify - Global Variable                    Uses Magic
  403.  
  404.          Declaration: (example) CenterJustify := true
  405.  
  406.          Description:
  407.          If you set the  boolean  global  CenterJustify  to  true  all
  408.          subsequent  calls  to Pop, Dialog, GetYN, GetAnyKey, Menu and
  409.          DoubleMenu will contain centered text.
  410.  
  411.          Considerations:
  412.             When a program starts,  CenterJustify  is  false.  If  you
  413.          change  CenterJustify  to true all subsequent uses of it will
  414.          remain true until you specifically change it back  to  false.
  415.          On  4.77  mhz computers (older models) this can slow menu and
  416.          pop-up generation  slightly.  Works  the  same  in  text  and
  417.          graphics modes.
  418.  
  419.          See Also:
  420.          Pop, GetAnyKey, GetYN, Dialog, Menu, Double Menu.
  421.  
  422.          Example:
  423.          Program Test;
  424.          uses magic;
  425.          begin
  426.             centerjustify := true;
  427.             sent[1] := 'This is a very long line of text to display';
  428.             sent[2] := 'This is short';
  429.             GetAnyKey(-1,-1);
  430.          end.
  431.  
  432.          Performance of example:
  433.          Two  lines of text will pop up on the screen and wait until a
  434.          user presses any key. The second line will be centered  under
  435.          the first.
  436.  
  437.          *************************************************************
  438.          CGAVideo - Procedure                               Uses Magic
  439.  
  440.          Declaration: CGAVideo
  441.  
  442.          Description:
  443.          This  initializes  the system in CGA graphics mode. CGA video
  444.          driver will be automatically compiled into the  .EXE  program
  445.          file, eliminating the need for external CGA.BGI file.
  446.  
  447.          Considerations:
  448.          Will  not  work  on Hercules-equipped computers. Graphmode is
  449.          initially set to 0 (see Borland manual for more details).  In
  450.          this  mode,  with  default  colors,  some  LCD laptops may be
  451.          unreadable. To repair, switch to another graphics  mode  with
  452.          SetGraphMode  {Borland  manual}.  The  resulting .EXE file is
  453.          much smaller than one compiled after  a  call  to  BestVideo.
  454.          This  must  be  called  only once during a program. Video.Tpu
  455.          must be available until after compilation.  Must  add  Graph,
  456.          Magic to Uses statement.
  457.  
  458.          See Also:
  459.          BestVideo,   HercVideo,   EGAVideo,   VGAVido,   SetGraphMode
  460.          {Borland}
  461.  
  462.          Example:
  463.          Program Test;
  464.          uses crt,graph, video, magic;
  465.          begin
  466.             CGAVideo;
  467.             rectangle(10,10,310,190);
  468.             repeat until keypressed;
  469.             CleanUp;
  470.          end.
  471.  
  472.          Performance of example:
  473.          The  system is put in CGA graphics mode. A large rectangle is
  474.          displayed   until  any  key  is  pressed.  The  program  then
  475.          terminates gracefully. The colors used for  this  example may
  476.          not be easily distinguished on a laptop LCD display. Crt must
  477.          be in the Uses line because keypressed is a procedure  within
  478.          the Crt unit (Turbo.tpl).
  479.  
  480.          *************************************************************
  481.          CleanUp - Procedure                                Uses Magic
  482.  
  483.          Declaration: CleanUp
  484.  
  485.          Description:
  486.          This procedure clears the screen, releases  memory  held  for
  487.          video  applications,  returns to standard text and background
  488.          colors  in  text  mode,  saves  and  closes   open  automatic
  489.          text files, resulting in a graceful return to DOS.
  490.  
  491.          Considerations:
  492.          Call CleanUp as the last line executed in a program. Works in
  493.          graphics and text modes.
  494.  
  495.          Example:
  496.          Program Test;
  497.          uses crt, graph, video, magic;
  498.          begin
  499.             CGAVideo;
  500.             rectangle(10,10,310,190);
  501.             repeat until keypressed;
  502.             CleanUp;
  503.          end.
  504.  
  505.          Performance of example:
  506.          The  system is put in CGA graphics mode. A large rectangle is
  507.          displayed   until  any  key  is  pressed.  The  program  then
  508.          terminates  gracefully  to the DOS prompt. Crt must be in the
  509.          Uses statement because keypressed is a procedure  within  the
  510.          Crt unit (Turbo.tpl).
  511.  
  512.          *************************************************************
  513.          Dialog - Procedure                                 Uses Magic
  514.  
  515.          Declaration: Dialog(x,y : integer)
  516.  
  517.          Description:
  518.              Dialog  requires  two  integers,  an x (horizontal) and y
  519.          (vertical) to establish the position of the upper left corner
  520.          of the dialog box on the screen.  In  text  mode,  the  upper
  521.          left corner is 1,1, and the lower right is 80,25. In graphics
  522.          mode  the upper left is 0,0, and the lower right is variable,
  523.          depending on the current graphics card and mode.
  524.              You  can  force  Dialog  to  pop-up  in the center of the
  525.          screen by using  a  negative  number  for  the  x  and the  y
  526.          positions.
  527.              Dialog will pop up a box on the screen  containing  lines
  528.          of  text  and  one  blank line at the bottom of the box.  The
  529.          user is prompted to type an answer in that bottom  line.  The
  530.          lines  that  will  be displayed are predeclared as the array:
  531.          sent[1..19].
  532.              To  use  Dialog,  you  must  first assign the text to the
  533.          array. Use as many lines as you like up  to  19,  as  in  the
  534.          example  below.  Dialog   will   automatically  ignore  lines
  535.          beyond those which contain your text. When the  user  presses
  536.          [Enter]  or  clicks  the  left  mouse  button, the dialog box
  537.          disappears. A new string exists called answer, which contains
  538.          what the user typed. The sent[1..19] array is cleared.
  539.              The user can type an answer string as long as the longest
  540.          sent[]  in the dialog box. To get a longer answer string, pad
  541.          any sent[] string with spaces to make the dialog box wider.
  542.              Dialog works in text or graphics mode.
  543.  
  544.          Considerations:
  545.              See  above.  In  graphics modes, must use  default  font.
  546.          (#0, bit-mapped)
  547.  
  548.          See also: sent[], Pop, GetYN, GetAnyKey, Menu
  549.  
  550.          Example:
  551.          Program Test;
  552.          uses magic;
  553.          var teststring : string;
  554.          begin
  555.             sent[1] := '    How would you answer this question?   ';
  556.             sent[2] := '            Any answer will do.';
  557.             dialog(-1,5);
  558.             teststring := answer;
  559.             .
  560.             .
  561.          end.
  562.  
  563.          Performance of example:
  564.          Only the first two strings from the array sent[]  are  filled
  565.          with  text.  Dialog  is called and pops a box onto the screen
  566.          containing only those two sent[]s, plus an empty line at  the
  567.          bottom.   The  program  then  waits  for  the user to type an
  568.          answer in the empty line then press [Enter] or click the left
  569.          mouse button. The dialog box  is  wider  than  the  questions
  570.          because  they  have  been padded with spaces. This allows the
  571.          user room for a long answer. Since the first  number  in  the
  572.          variables passed to Dialog is  a  -1,  the  box  is  centered
  573.          horizontally  on  the screen. After the user finishes typing,
  574.          the dialog box disappears, leaving a  string  called  answer.
  575.          The  TestString is a copy of answer and the program can go on
  576.          to process it as desired.
  577.  
  578.          *************************************************************
  579.          DoubleMenu - Procedure                             Uses Magic
  580.  
  581.          Declaration: DoubleMenu(x,y : integer)
  582.  
  583.          Description:
  584.              DoubleMenu is like Menu, but puts a wider pop-up menu box
  585.          on  the  screen  showing  the  menu  choices (sent[]s) in two
  586.          columns, thereby accommodating up to 36 menu choices.
  587.              Two integer parameters are required, the first  indicates
  588.          the  horizontal  position  of  the  upper left corner and the
  589.          second is for the vertical position.  If either integer is  a
  590.          negative  number,   that integer will be ignored and the menu
  591.          will be centered on the screen in that dimension.
  592.              Before calling DoubleMenu, a byte variable, mc should  be
  593.          given  a  value.   mc  is the current MenuChoice, meaning the
  594.          sent[] corresponding to mc is the one  highlighted.   If  you
  595.          state:  mc  :=  1  then  the  first  item on the menu will be
  596.          highlighted.  If you forget  to  assign  mc,  a  random  menu
  597.          choice   will   be   highlighted  with  your  first  call  to
  598.          DoubleMenu.
  599.              DoubleMenu is very much like a  regular  pop-up  box,  in
  600.          that  it  will  contain  the  sent[]s  in the manner you have
  601.          declared them. But additionally, the item corresponding to mc
  602.          will be highlighted.  While the user uses the arrow  keys  or
  603.          moves  the  mouse,  the  highlight  bar will move from one to
  604.          another of the sent[]s. When the user presses  any  non-arrow
  605.          key  or  clicks  a  left  mouse button, the pop-up DoubleMenu
  606.          disappears, all sent[]s are set to '', and U will have a char
  607.          value corresponding to the key pressed.  If  the  left  mouse
  608.          button  was  clicked  U  will  be char #174, and if the right
  609.          button was pressed, U will be #175.
  610.              You can then use U or mc to perform operations related to
  611.          your user's choice. To have the menu return  to  the  screen,
  612.          sent[]s  must  be  refilled  with your strings and DoubleMenu
  613.          must  be  called again. The usual way to use DoubleMenu is to
  614.          put it into a repeat loop as shown in the example below.
  615.  
  616.          Considerations:
  617.             Maximum sent[]s : 36; Should assign a value to  mc  of  at
  618.          least  one and less than the maximum sent[]. Must re-fill the
  619.          sent[]s for subsequent calls to DoubleMenu.  If in a graphics
  620.          mode, you must use DefaultFont (0) with DoubleMenu.
  621.             In  graphics  modes,  must  use  Borland  DefaultFont (#0,
  622.          bit-mapped)
  623.  
  624.          See also: sent[], Pop, GetYN, GetAnyKey, Menu
  625.  
  626.          Example:
  627.          Program Test;
  628.          uses magic;
  629.          begin
  630.             mc := 1;
  631.             repeat
  632.                sent[1] := 'Do Thing One';
  633.                sent[2] := 'Do Thing Two';
  634.                sent[3] := 'Do Thing tHree';
  635.                sent[4] := 'Do Thing Four';
  636.                sent[5] := 'Do Thing fiVe';
  637.                sent[6] := 'Do Thing Six';
  638.                sent[7] := '   Quit   ';
  639.                DoubleMenu(10,-1);
  640.                if (u = #174) or (u = #13) then
  641.                case mc of
  642.                   1 : Procedure1;
  643.                   2 : Procedure2;
  644.                   3 : Procedure3;
  645.                   4 : Procedure4;
  646.                   5 : Procedure5;
  647.                   6 : Procedure6;
  648.                   7 : u := #175;
  649.                end; {case mc}
  650.                u := upcase(u);
  651.                case u of
  652.                   'O' : Procedure1;
  653.                   'T' : Procedure2;
  654.                   'H' : Procedure3;
  655.                   'F' : Procedure4;
  656.                   'V' : Procedure5;
  657.                   'S' : Procedure6;
  658.                   'Q' : u := #175;
  659.                  #27: u := #175;
  660.                end; {case u}
  661.             until U = #175;
  662.             CleanUp;
  663.          end.
  664.  
  665.          Performance of example:
  666.             Mc is set to 1 so when the menu pops up,  the  first  item
  667.          will  be  highlighted.  Seven  sent[]s are given strings. The
  668.          DoubleMenu pops up and the user presses a key or operates the
  669.          mouse. Then if U is #174, (because the left mouse button  has
  670.          been pressed) or U is #13, (the  [Enter]  key)  then  a  case
  671.          statement figures out what to do with the user's menu choice.
  672.             If mc is between 1 and 6, one of the procedures is called.
  673.          Of  course,  these procedures can do anything you wish, based
  674.          upon what menu item the user  has  selected.  The  last  menu
  675.          choice  (sent[7])  is  'Quit'  and will cause this program to
  676.          fall through and terminate.
  677.             U  is  changed  into  an  uppercase  letter  so  that  the
  678.          following  case  will work whether the user presses a capital
  679.          or small letter. This second case checks to see  whether  the
  680.          user  selected  a menu item based upon the capitalized letter
  681.          hints. You can also  use  function  keys  here.  The  #0  has
  682.          already  been stripped off, so if you get a ';' then the user
  683.          pressed [F1] and probably wants 'help.'
  684.             There is a boolean variable called Functkey which will now
  685.          be true if the user pressed a function key, such as an  arrow
  686.          or  [F1]. If the user actually pressed [;] then Functkey will
  687.          be false.
  688.              Assuming  the user did not select  'Quit'  or  press  #27
  689.          (the [Escape] key)  or  the  right  mouse  button,  the  menu
  690.          process will repeat.
  691.              When  the  user  finally does choose to quit, the CleanUp
  692.          procedure returns to DOS gracefully.
  693.  
  694.          *************************************************************
  695.          DumpMaps - Procedure                               Uses Magic
  696.  
  697.          Declaration: DumpMaps
  698.  
  699.          Description:
  700.             DumpMaps  will  release all memory held for screen images,
  701.          without restoring the images. Works the same in  graphics  or
  702.          text modes.
  703.  
  704.          Considerations:
  705.              In  graphics  modes, it is easy to fill all available RAM
  706.          with unused screen images. This seldom-needed procedure  will
  707.          help you clear that out.
  708.  
  709.          See  also:  Restore,  Pop,  GetAnyKey,  GetYN,  Dialog, Menu,
  710.          DoubleMenu, XClear, CleanUp
  711.  
  712.          Example:
  713.          Program Test;
  714.          uses video, graph, magic;
  715.          begin
  716.             BestVideo;
  717.             sent[1] := 'An example string';
  718.             sent[2] := 'Another example string';
  719.             pop(10,10);
  720.             sent[1] := 'An example string';
  721.             sent[2] := 'Another example string';
  722.             pop(0,0);
  723.             sent[1] := 'An example string';
  724.             sent[2] := 'Another example string';
  725.             pop(getmaxx div 2,160);
  726.             sent[1] := 'This is becoming a messy screen';
  727.             pop(40,getmaxy - 40);
  728.             WaitForUser;
  729.             DumpMaps;
  730.             .
  731.             .
  732.          end.
  733.  
  734.          Performance of example:
  735.             The screen is cluttered with a bunch of pop-up boxes. When
  736.          the user presses a key, the memory held for  the  replacement
  737.          of  those  boxes  disappears, but he boxes remain pictured on
  738.          the screen.
  739.  
  740.          *************************************************************
  741.          EGAVideo - Procedure                               Uses Magic
  742.  
  743.          Declaration: EGAVideo
  744.  
  745.          Description:
  746.          This  initializes  the system in EGA graphics mode. EGA video
  747.          driver will be automatically compiled into the  .EXE  program
  748.          file, eliminating the need for external EGAVGA.BGI file.
  749.  
  750.          Considerations:
  751.              The resulting .EXE file is much smaller than one compiled
  752.          after a call to BestVideo.   BestVideo  builds  all  graphics
  753.          drivers  into  the .EXE file, but EGAVideo builds in only the
  754.          EGAVGA driver.  This  must  be  called  only  once  during  a
  755.          program. Video.Tpu must be available until after compilation.
  756.          Must add Graph, Video, Magic to Uses statement.
  757.              There  are  several graphmodes available for EGA. See the
  758.          Borland manuals.
  759.              The magic unit allows for more screen  saves  when  using
  760.          multiple pop-up boxes, GetYN's, etc than RAM can hold. If you
  761.          go to far, stacking up too many pop-ups,  the IDE will report
  762.          a memory error.
  763.  
  764.          See Also:
  765.          BestVideo,     HercVideo,    CGAVideo,    VGAVido    {Magic};
  766.          SetGraphMode, Setcolor, etc. {Borland}
  767.  
  768.          Example:
  769.          Program Test;
  770.          uses crt, graph, video, magic;
  771.          begin
  772.             EGAVideo;
  773.             rectangle(10,10,20,20);
  774.             repeat until keypressed;
  775.             CleanUp;
  776.          end.
  777.  
  778.          Performance of example:
  779.          The  system is put in EGA graphics mode. A small rectangle is
  780.          displayed in the upper left corner of the  screen  until  any
  781.          key  is pressed.  The program then terminates gracefully. Crt
  782.          must be in the Uses line because Keypressed  is  a  procedure
  783.          within the Crt unit (Turbo.tpl).
  784.  
  785.          *************************************************************
  786.          FileRead - Procedure                               Uses Magic
  787.  
  788.          Declaration: character variable := FileRead
  789.  
  790.          Description:
  791.             Fileread  is  a  function  that  automatically  reads  one
  792.          character  from a pre-declared text file. Opening and closing
  793.          the textfile is automatic. Only one character is read and the
  794.          next call to FileRead will get  the  next  character  in  the
  795.          file.  To get the very first character in the file, Reset the
  796.          file before calling Fileread.
  797.  
  798.          Considerations:
  799.          The file is called 'Infile' within the program, but must have
  800.          an external name under which it will be stored on  disk.  You
  801.          must  first  call  NameInFile, before using FileRead, or else
  802.          the program will try to read a file with the default external
  803.          name of 'NoName.' If there is an error,  such  as  trying  to
  804.          read  past  the  end of the file, or reading a file that does
  805.          not exist, FileRead will return a char #0.
  806.  
  807.          See Also:
  808.          NameInFile, FileReadLn, problem {Magic} Reset, EOF {Borland}
  809.  
  810.          Example:
  811.          Program Reader;
  812.          uses magic;
  813.          var a : integer;
  814.          begin
  815.             XClear;
  816.             NameInFile('sample.doc');
  817.             for a := 1 to 1000 do write(fileread);
  818.          end.
  819.  
  820.          Performance of example:
  821.          The screen is cleared. The file to read will be 'Sample.Doc'.
  822.          Assuming  the  file  exists,  the  first 1000 characters from
  823.          that file will be displayed on the screen, then  the  program
  824.          ends.
  825.  
  826.          *************************************************************
  827.          FileReadln - Procedure                             Uses Magic
  828.  
  829.          Declaration: string variable := FileRead
  830.  
  831.          Description:
  832.             Filereadln is a function that automatically reads one line
  833.          from  a  pre-declared  text  file.   Opening  and closing the
  834.          textfile is automatic.  Only one line is read  and  the  next
  835.          call  to  FileReadln  will get the next line in the file.  To
  836.          get the very first line in the file, Reset  the  file  before
  837.          calling  Fileread.  A  line  is  defined  as  having carriage
  838.          return/linefeed at the end (char #13,#10).
  839.  
  840.          Considerations:
  841.          The file is called 'Infile' within the program, but must have
  842.          an external name under which it will be stored on  disk.  You
  843.          must first call NameInFile, before using FileReadln, or  else
  844.          the program will try to read a file with the default external
  845.          name  of  'NoName.'  If  there is an error, such as trying to
  846.          read past the end of the file, or reading a  file  that  does
  847.          not exist, FileReadln will return a char #0.
  848.  
  849.          See Also:
  850.          NameInFile, FileReadLn, problem {Magic} Reset, EOF {Borland}
  851.  
  852.          Example:
  853.          Program Reader;
  854.          uses magic;
  855.          var a : integer;
  856.          begin
  857.             XClear;
  858.             NameInFile('sample.doc');
  859.             for a := 1 to 10 do writeln(FileReadLn);
  860.          end.
  861.  
  862.          Performance of example:
  863.          The screen is cleared. The file to read will be 'Sample.Doc'.
  864.          Assuming  the  file exists, the first 10 lines from that file
  865.          will be displayed on the screen, then the program ends.
  866.  
  867.          *************************************************************
  868.          FileWrite - Procedure                              Uses Magic
  869.  
  870.          Declaration: Filewrite(xstring : string)
  871.  
  872.          Description:
  873.              Filewrite   will   write  a string into the standard text
  874.          output    file.   Opening  and  closing  the  file is handled
  875.          automatically.  If  the  file  exists,  the  string  will  be
  876.          appended  to  the end.  If the file does not exist it will be
  877.          created. Carriage return/linefeed is not added to the end  of
  878.          the string.
  879.  
  880.          Considerations:
  881.          The   standard  text  output  file is called 'OutFile' within
  882.          Pascal, , but must have an external name under which it  will
  883.          be  stored  on disk.  You must first call NameOutFile, before
  884.          using  FileWrite, or else the program will write to file with
  885.          the default external name of 'NoName.' If there is an  error,
  886.          nothing  will  be  written  to disk and the boolean variable,
  887.          Problem  will  be  true.  Only one string or character can be
  888.          written to the output file with a single call  to  FileWrite.
  889.          No  numerical values can be written  unless  they  are  first
  890.          converted to a string.
  891.  
  892.          See Also:
  893.          NameOutFile, FileWriteLn, Problem {Magic} Str {Borland}
  894.  
  895.          Example:
  896.          Program Writer;
  897.          uses magic;
  898.          begin
  899.             NameOutFile('sample.doc');
  900.             FileWrite('This is a sample text file.');
  901.             FileWrite('This is a second string of text.');
  902.          end.
  903.  
  904.          Performance of example:
  905.          The  standard  text file is renamed 'Sample.Doc.' Two strings
  906.          are written to the file then the program ends.  If there  was
  907.          no  previous  file  by  that  name,  Sample.Doc  is  created,
  908.          otherwise the line is appended to the end of the  other  text
  909.          in  the file. If you look at Sample.Doc with a word processor
  910.          or text editor or Turbo Pascal IDE, you  will  see  the  last
  911.          line   in  the file is: 'This is a sample text file.  This is
  912.          a second string of text.'
  913.  
  914.          *************************************************************
  915.          FileWriteLn - Procedure                            Uses Magic
  916.  
  917.          Declaration: FilewriteLn(xstring : string)
  918.  
  919.          Description:
  920.              FilewriteLn  will  write  a string into the standard text
  921.          output  file.   Opening  and  closing  the  file  is  handled
  922.          automatically.   If  the  file  exists,  the  string  will be
  923.          appended to the end.  If the file does not exist it  will  be
  924.          created.  Carriage return/linefeed is added to the end of the
  925.          string.
  926.  
  927.          Considerations:
  928.          The   standard  text  output  file is called 'OutFile' within
  929.          Pascal, , but must have an external name under which it  will
  930.          be  stored  on disk.  You must first call NameOutFile, before
  931.          using  FileWrite, or else the program will write to file with
  932.          the default external name of 'NoName.' If there is an  error,
  933.          nothing  will  be  written  to disk and the boolean variable,
  934.          Problem  will  be  true.  Only one string or character can be
  935.          written to the output file with a single call to FileWriteLn.
  936.          No numerical values can be  written  unless  they  are  first
  937.          converted to a string.
  938.  
  939.          See Also:
  940.          NameOutFile, FileWrite, Problem {Magic} Str {Borland}
  941.  
  942.          Example:
  943.          Program Writer;
  944.          uses magic;
  945.          begin
  946.             NameOutFile('sample.doc');
  947.             FileWriteLn('This is a sample text file.');
  948.             FileWriteLn('This is a second string of text.');
  949.          end.
  950.  
  951.          Performance of example:
  952.          The standard text file is renamed 'Sample.Doc.'  Two  strings
  953.          are  written to the file then the program ends.  If there was
  954.          no  previous  file  by  that  name,  Sample.Doc  is  created,
  955.          otherwise  the  line is appended to the end of the other text
  956.          in the file. If you look at Sample.Doc with a word  processor
  957.          or  text  editor  or  Turbo Pascal IDE, you will see the last
  958.          lines in the file are: 'This is a sample text file.
  959.                                  This is a second string of text.'
  960.  
  961.          *************************************************************
  962.          FunctAscii - Function                              Uses Magic
  963.  
  964.          Declaration: var x : char; x := FunctAscii
  965.  
  966.          Description:
  967.              Returns a character value representing the ASCII value of
  968.          a  function  key  or an extended key ([Alt] + x, for example)
  969.          has been pressed.  Returns 0  if  a  standard  key  has  been
  970.          pressed.
  971.  
  972.          Considerations:
  973.             If you want to know which function key  has  been  pressed
  974.          you must call FunctAscii  before  any  further  uses  of  the
  975.          global variable U or the function XReadKey.
  976.  
  977.          See Also:
  978.          XReadKey, Menu, DoubleMenu, U
  979.  
  980.          Example:
  981.          Program test;
  982.          uses crt, magic;
  983.          var
  984.             hold : char;
  985.          begin
  986.             repeat
  987.                u := readkey;
  988.                clrscr;
  989.                hold := FunctAscii;
  990.                if hold = #0 then write(U)
  991.                   else write('Function key: ',hold);
  992.             until u = #27;
  993.          end.
  994.  
  995.          Performance of example:
  996.              Everytime  a key is pressed the screen is cleared and the
  997.          character value of the key is written on the screen.  If  the
  998.          key  is  an extended key, the value of the key is preceded by
  999.          "Function key:" When the user presses the [Esc] key (#27) the
  1000.          program ends.
  1001.  
  1002.          *************************************************************
  1003.          FunctKey - Global Variable                         Uses Magic
  1004.  
  1005.          Declaration: (example) if FunctKey then
  1006.  
  1007.          Description:
  1008.              FunctKey is returned with calls to Menu or DoubleMenu. If
  1009.          the user presses a key which is a  function  key,  the  ASCII
  1010.          equivalent of that key is assigned to U and FunctKey is true.
  1011.          If the key pressed was not a function key, FunctKey is false.
  1012.              This is useful for differentiating when a user presses an
  1013.          [F] (function) key instead of an alphanumeric key.
  1014.  
  1015.          Considerations:
  1016.              FunctKey  is  reset to false at the start of each call to
  1017.          Menu or DoubleMenu.
  1018.  
  1019.          See Also:
  1020.          Menu, DoubleMenu.
  1021.  
  1022.          Example:
  1023.          Program Test;
  1024.          uses magic;
  1025.          begin
  1026.             mc := 1;
  1027.             repeat
  1028.                sent[1] := 'Do Something';
  1029.                sent[2] := 'Do Something Else';
  1030.                menu(-1,-1);
  1031.                if u = #13 then
  1032.                begin
  1033.                   if mc = 1 then DoSomething;
  1034.                   if mc = 2 then DoTheOtherThing;
  1035.                end;
  1036.                if (u = ';') and (FunctKey) then DisplayHelp;
  1037.             until u = #27;
  1038.          end.
  1039.  
  1040.          Performance of example:
  1041.          A menu is displayed  with  only  two  options.  If  the  user
  1042.          presses  [Enter]  while  the  highlight  bar  is on the first
  1043.          option, procedure DoSomething is executed, and if the  second
  1044.          option  is  highlighted  then  procedure  DoTheOtherThing  is
  1045.          executed. This repeats until the user presses the  [Esc]  key
  1046.          (ASCII  #27). There is one other option.  If the user presses
  1047.          the  [F1]  key then  FunctKey  is  true  and  U  is  ';.'  In
  1048.          this case procedure DisplayHelp will run.
  1049.  
  1050.          *************************************************************
  1051.          Gd - Global Variable                               Uses Magic
  1052.  
  1053.          Declaration: (example) gd := 2
  1054.  
  1055.          Description:
  1056.              Gd is a global integer variable for GraphDetect.
  1057.  
  1058.          Considerations:
  1059.             See Borland manual for more information.
  1060.  
  1061.          See Also:
  1062.          Initgraph {Borland}
  1063.  
  1064.          *************************************************************
  1065.          GetAnyKey - Procedure                              Uses Magic
  1066.  
  1067.          Declaration: GetAnyKey(x,y : integer)
  1068.  
  1069.          Description:
  1070.              This is for pop-up notices. A  message  pops  up  on  the
  1071.          screen  then  waits  for the user to press any key or click a
  1072.          mouse button. You must write strings for the array of sent[]s
  1073.          before  calling this procedure. After the user presses a key,
  1074.          all traces of the pop-up and the sent[]s disappear.
  1075.              GetAnyKey  requires  two  integer  variables,  the  first
  1076.          determines the horizontal position on  the  screen,  and  the
  1077.          second  is  the  vertical  coordinate.  If  either  number is
  1078.          negative, the pop-up message will be centered on  the  screen
  1079.          in the corresponding dimension.
  1080.  
  1081.          Considerations:
  1082.             Maximum sentc array size: 18. Make sure to add something to
  1083.          this effect to every message to avoid confusing  your  users:
  1084.          "Press any key to continue..."
  1085.  
  1086.          See Also:
  1087.          Menu, DoubleMenu, Pop, Dialog, GetYN, sent[].
  1088.  
  1089.          Example:
  1090.          Program Test;
  1091.          uses magic;
  1092.          begin
  1093.             .
  1094.             .
  1095.             sent[1] := 'You have selected an option available only';
  1096.             sent[2] := 'to registered users. Please send money!!!';
  1097.             sent[3] := 'Press any key to continue...';
  1098.             GetAnyKey(-1,-1);
  1099.             .
  1100.             .
  1101.          end.
  1102.  
  1103.          Performance of example:
  1104.              A box pops up on the screen containing three lines,  then
  1105.          disappears  without  a trace when the user presses any key or
  1106.          clicks a mouse button.
  1107.  
  1108.          *************************************************************
  1109.          GetYN - Procedure                                  Uses Magic
  1110.  
  1111.          Declaration: GetYN(x,y : integer)
  1112.  
  1113.          Description:
  1114.               A message pops up on the screen then waits for the  user
  1115.          to  press  'Y' or 'N' or click a mouse button. You must write
  1116.          strings  for  the  array  of  sent[]s  before  calling   this
  1117.          procedure.  After  the  user presses a key, all traces of the
  1118.          pop-up and the sent[]s disappear.
  1119.              GetYN  requires  two   integer   variables,   the   first
  1120.          determines  the  horizontal  position  on the screen, and the
  1121.          second is the  vertical  coordinate.   If  either  number  is
  1122.          negative,  the  pop-up message will be centered on the screen
  1123.          in the corresponding dimension.
  1124.              GetYN  sets  the  global  string,  answer, to 'Y' or 'N'.
  1125.          Also, the global char U is set to 'Y' or 'N.'
  1126.  
  1127.          Considerations:
  1128.             Maximum sent array size: 18. Make sure to add something to
  1129.          this effect to every message to avoid confusing  your  users:
  1130.          "Press [Y] or [N]..." GetYN is not case sensitive.  The  user
  1131.          can type upper or lower case [y] or [n]. If  the  left  mouse
  1132.          button is clicked answer is set to 'Y' and if the right mouse
  1133.          button is clicked answer = 'N'.
  1134.  
  1135.          See Also:
  1136.          Menu, DoubleMenu, Pop, Dialog, GetYN, sent[], answer, u.
  1137.  
  1138.          Example:
  1139.          Program Test;
  1140.          uses magic;
  1141.          begin
  1142.             .
  1143.             .
  1144.             sent[1] := 'Exit to Dos? (Y/N)';
  1145.             GetYN(-1,1);
  1146.             if answer = 'Y' then
  1147.             begin
  1148.                CleanUp;
  1149.                halt;
  1150.             end;
  1151.             .
  1152.             .
  1153.          end.
  1154.  
  1155.          Performance of example:
  1156.              A box pops up on the screen containing one line and waits
  1157.          for the user to press a key. Until the key pressed  is  upper
  1158.          or lower case 'Y' or 'N', or until the user  clicks  a  mouse
  1159.          key,  the box remains. Then the global string, answer, is set
  1160.          to 'Y' or 'N.' If answer = 'N' then  the  program  terminates
  1161.          cleanly.
  1162.  
  1163.          *************************************************************
  1164.  
  1165.          Gm - Global Variable                               Uses Magic
  1166.  
  1167.          Declaration: (example) gm := 0
  1168.  
  1169.          Description:
  1170.              Gm is a global integer variable for GraphMode.
  1171.  
  1172.          Considerations:
  1173.             See Borland manual for more information.
  1174.  
  1175.          See Also:
  1176.          Initgraph, SetGraphMode {Borland}
  1177.  
  1178.          *************************************************************
  1179.          Gothic - Procedure                                 Uses Magic
  1180.  
  1181.          Declaration: Gothic
  1182.  
  1183.          Description:
  1184.              Calling  the  procedure  Gothic  makes the Borland Gothic
  1185.          font available to graphic-based programs. This font  will  be
  1186.          compiled  into  the  .EXE  file.  GOTHIC.CHR does not have to
  1187.          accompany the finished product.
  1188.  
  1189.          Considerations:
  1190.          Compiled .EXE size increases by about 17k.  Must  put  Fonts,
  1191.          Graph, Video, Magic in Uses statement. Do not use  with  Pop,
  1192.          GetAnyKey,  GetYN,  Dialog,  Menu or DoubleMenu. To use type:
  1193.          SetTextStyle(GothicFont,d,x) where d is the direction  (0  is
  1194.          horizontal) and x is an integer from 1 to 10 representing the
  1195.          relative size of the text.
  1196.  
  1197.          See Also:
  1198.          BestVideo,  CGAVideo, EGAVideo, VGAVideo, SansSerif, Triplex,
  1199.          Small {Magic} SetTextStyle {Borland}
  1200.  
  1201.          Example:
  1202.          Program Test;
  1203.          uses crt, fonts, graph, video, magic;
  1204.          begin
  1205.             BestVideo;
  1206.             Gothic;
  1207.             SetTextStyle(GothicFont,0,2);
  1208.             outtextxy(100,90,'Test');
  1209.             repeat until keypressed;
  1210.          end.
  1211.  
  1212.          Performance of example:
  1213.             Gothic font information is compiled into  the  .EXE  file.
  1214.          The  highest resolution graphics mode is selected. GothicFont
  1215.          is selected for output, then the word 'Test'  is  written  on
  1216.          the  screen.  When  the  user  presses  a  key,  the  program
  1217.          terminates.  Crt  must be in the Uses line because Keypressed
  1218.          is a procedure within the Crt unit (Turbo.tpl).
  1219.  
  1220.          *************************************************************
  1221.          HercVideo - Procedure                              Uses Magic
  1222.  
  1223.          Declaration: HercVideo
  1224.  
  1225.          Description:
  1226.          This  initializes  the  system  in  Hercules  graphics  mode.
  1227.          Hercules video driver will be automatically compiled into the
  1228.          .EXE program file, eliminating the need for external Herc.BGI
  1229.          file.
  1230.  
  1231.          Considerations:
  1232.              The resulting .EXE file is much smaller than one compiled
  1233.          after a call to BestVideo.   BestVideo  builds  all  graphics
  1234.          drivers  into the .EXE file, but HercVideo builds in only the
  1235.          Herc.BGI driver.  This must be  called  only  once  during  a
  1236.          program. Video.Tpu must be available until after compilation.
  1237.          There is only one GraphMode for Hercules, which  is  0.  Must
  1238.          add Graph, Video, Magic to  Uses  statement.  With  many  VGA
  1239.          cards,  you  must  leave  Turbo  Pascal, specifically run the
  1240.          video card software to set it to Hercules mode, then  compile
  1241.          and run your program.
  1242.  
  1243.          See Also:
  1244.          BestVideo,     CGAVideo,    EGAVideo,    VGAVido    {Magic};
  1245.          SetGraphMode, Setcolor, etc. {Borland}
  1246.  
  1247.          Example:
  1248.          Program Test;
  1249.          uses crt, Graph, Video, Magic;
  1250.          begin
  1251.             HercVideo;
  1252.             rectangle(10,10,20,20);
  1253.             repeat until keypressed;
  1254.             CleanUp;
  1255.          end.
  1256.  
  1257.          Performance of example:
  1258.          The  system  is  put  in  Hercules  graphics  mode.  A  small
  1259.          rectangle is displayed in the upper left corner of the screen
  1260.          until any  key  is  pressed.   The  program  then  terminates
  1261.          gracefully. Crt must be in the Uses line  because  Keypressed
  1262.          is a procedure within the Crt unit (Turbo.tpl).
  1263.  
  1264.          *************************************************************
  1265.          HideCursor - Procedure                             Uses Magic
  1266.  
  1267.          Declaration: HideCursor
  1268.  
  1269.          Description:
  1270.          This  makes the cursor disappear until it is moved to another
  1271.          screen location. Generally,  use  it  after  writing  to  the
  1272.          screen when the user is not to type input.
  1273.  
  1274.          Considerations:
  1275.             For text mode only, has no effect in graphics.
  1276.  
  1277.          Example:
  1278.          Program Test;
  1279.          uses magic;
  1280.          begin
  1281.             write('There is no cursor at the end of this line.');
  1282.             hidecursor;
  1283.             u := xreadkey;
  1284.          end.
  1285.  
  1286.          Performance of example:
  1287.             A  line  of  text  appears  on the screen, but there is no
  1288.          cursor at the end of the line.
  1289.  
  1290.          *************************************************************
  1291.          InFile - Global Variable                           Uses Magic
  1292.  
  1293.          Declaration: (example) assign(InFile,'Things.Doc')
  1294.  
  1295.          Description:
  1296.             InFile  is declared globally as a file of type Text. It is
  1297.          used for importing information into  your  program  with  the
  1298.          automatic procedures FileRead and FileReadLn.
  1299.  
  1300.          Considerations:
  1301.             InFile  is  for  text  only.  Numeric   values   will   be
  1302.          represented  as  strings  in  InFile.  You  can  override the
  1303.          automatic  use  of  InFile   with   standard   Turbo   Pascal
  1304.          techniques such as Assign, ReWrite and Close.
  1305.  
  1306.          See Also:
  1307.          FileWrite, FileWriteLn, NameInFile, OutFile {Magic};
  1308.          Assign,   ReWrite,   ReSet,  Append,  Write,  WriteLn,  Read,
  1309.          ReadLn, Rename, Erase, Close {Borland}
  1310.  
  1311.          Example:
  1312.          Program Test;
  1313.          uses magic;
  1314.          begin
  1315.             NameInFile('TestFile.Txt');
  1316.             ReWrite(InFile);
  1317.             close(InFile);
  1318.          end.
  1319.  
  1320.          Performance of example:
  1321.             This nasty little program makes sure that if  there  is  a
  1322.          file  called  'TestFile.Txt'  it will contain no information,
  1323.          since ReWriting a file wipes out any previous version of that
  1324.          file.
  1325.  
  1326.          *************************************************************
  1327.          Left - Global Variable                             Uses Magic
  1328.  
  1329.          Declaration: (example) if left = false then
  1330.  
  1331.          Description:
  1332.             Left is a global  boolean  variable  used  to  record  the
  1333.          status  of  the  left  mouse button.  If left = true then the
  1334.          left mouse button has been pressed.
  1335.  
  1336.          Considerations:
  1337.             The status of left will change with every  call  to  Poll,
  1338.          Waste,  WasteMouse,  ResetMouse  or  procedures  within Magic
  1339.          which handle text or pop up boxes.
  1340.  
  1341.          See Also: Poll, Waste, WasteMouse, ResetMouse, Right
  1342.  
  1343.          Example:
  1344.          Program Test;
  1345.          uses magic;
  1346.          var
  1347.             x, y : word;
  1348.          begin
  1349.             sent[1] := 'Nothing will change until you click the';
  1350.             sent[2] := 'left mouse button';
  1351.             Pop(-1,-1);
  1352.             WasteMouse;
  1353.             repeat poll(x,y,left,right) until left;
  1354.          end.
  1355.  
  1356.          Performance of example:
  1357.             A box containing two lines of text will stay on the screen
  1358.          until the user clicks the left  mouse  button.   The  program
  1359.          will then terminate.
  1360.  
  1361.          *************************************************************
  1362.          LittleCursor - Procedure                            Uses Magic
  1363.  
  1364.          Declaration: LittleCursor
  1365.  
  1366.          Description:
  1367.          After a call to LittleCursor, the cursor in  text  mode  will
  1368.          be a block the size of an underline instead of a large block.
  1369.          The  little cursor size is the DOS default cursor. Therefore,
  1370.          this procedure is generally used as an antidote to BigCursor.
  1371.  
  1372.          Considerations:
  1373.             Will have no effect in graphics mode, but will resume as a
  1374.          little cursor when returned to text mode.
  1375.  
  1376.          See also: BigCursor.
  1377.  
  1378.          Example:
  1379.          program test;
  1380.          uses magic;
  1381.          begin
  1382.             .
  1383.             .
  1384.             BigCursor;
  1385.             .
  1386.             .
  1387.             LittleCursor;
  1388.             CleanUp;
  1389.          end.
  1390.  
  1391.          Performance of Example:
  1392.          This  program  will  switch to a block size cursor, then just
  1393.          before ending, it returns the cursor to the default size.
  1394.  
  1395.          *************************************************************
  1396.          MainBack - Global Variable                         Uses Magic
  1397.  
  1398.          Declaration: MainBack := color
  1399.  
  1400.          Description:
  1401.          This sets the background color for the main  portion  of  the
  1402.          screen, outside of pop-up boxes. 'Color' is an integer from 0
  1403.          to    15    or   a   color constant as defined by Borland. Do
  1404.          not use colors above 7 in text mode.
  1405.  
  1406.          Considerations:
  1407.          May  not  have the expected effect when used with the limited
  1408.          palettes of 4-color CGA (mode  0,1  or  2),  2-color  CGA  or
  1409.          Hercules. In text mode, since this  is  a  background  color,
  1410.          only 8 colors are available: 0 - 7.
  1411.  
  1412.          See   also:  BarBack  BarText,  BoxBack,  BoxText,  MainText,
  1413.          Border, shadow
  1414.  
  1415.          Example:
  1416.          program test;
  1417.          uses magic;
  1418.          begin
  1419.             sent[1] := 'First Thing';
  1420.             sent[2] := 'Second Thing';
  1421.             sent[3] := 'Quit';
  1422.             mc := 1;
  1423.             MainBack := Red;
  1424.             XClear;
  1425.             Menu(-1,-1);
  1426.             .
  1427.             .
  1428.          end.
  1429.  
  1430.          Performance of example:
  1431.          Three strings are declared, and a menu pops up.  Because of
  1432.          the preceding change to MainBack, then the call to XClear,
  1433.          the main background around the menu is red.
  1434.  
  1435.          *************************************************************
  1436.          MainText - Global Variable                         Uses Magic
  1437.  
  1438.          Declaration: MainText := color
  1439.  
  1440.          Description:
  1441.          This  sets the text color for the main portion of the screen,
  1442.          outside of pop-up boxes. 'Color' is an integer from 0  to  15
  1443.          or  a color constant as defined by Borland.  Colors  are  the
  1444.          same in graphics and text modes.
  1445.  
  1446.          Considerations:
  1447.          May  not  have the expected effect when used with the limited
  1448.          palettes of 4-color CGA (mode  0,1  or  2),  2-color  CGA  or
  1449.          Hercules. No procedures in the  Magic  unit  use  this  color
  1450.          directly.
  1451.  
  1452.          See   also:  BarBack  BarText,  BoxBack,  BoxText,  MainBack,
  1453.          border, shadow
  1454.  
  1455.          Example:
  1456.          program test;
  1457.          uses magic;
  1458.          begin
  1459.             MainText:= LightGreen;
  1460.             textcolor(MainText);
  1461.             gotoxy(1,25);
  1462.             write('My Program, Copyright 1991, Your Company');
  1463.             sent[1] := 'First Thing';
  1464.             sent[2] := 'Second Thing';
  1465.             sent[3] := 'Quit';
  1466.             mc := 1;
  1467.             Menu(-1,-1);
  1468.             .
  1469.             .
  1470.          end.
  1471.  
  1472.          Performance of example:
  1473.              MainText  is  used  as a variable to hold "red." The text
  1474.          foreground color is set to MainText (red) and then  a  string
  1475.          is  written  on  the  bottom line of the screen: "My Program,
  1476.          Copyright 1991, Your Company." Then a menu pops up.
  1477.  
  1478.          *************************************************************
  1479.          MakeBox - Procedure                                Uses Magic
  1480.  
  1481.          Declaration: MakeBox(x,y,x1,y1 : integer)
  1482.  
  1483.          Description:
  1484.              MakeBox is a rather simple procedure  which  generates  a
  1485.          box on the screen. The box will appear in BoxBack color, with
  1486.          a border of border color. x and y are the integer coordinates
  1487.          of  the upper left corner, and x1 and y1 mark the lower right
  1488.          corner.  If in text mode the upper left corner of the  screen
  1489.          is  1,1  and  the lower right is 80,25. In graphics modes the
  1490.          upper left is 0,0 and the lower right varies with the current
  1491.          graphics mode.  In VGA 640 x 480,  for  instance,  the  lower
  1492.          right corner coordinates are 639,479.
  1493.  
  1494.          Considerations:
  1495.              Unlike the other pop-ups, this one does not save what  is
  1496.          displayed  under  the  box.   There is no way to get rid of a
  1497.          MakeBox  other  than  writing  something  else  over  it,  or
  1498.          regenerating  the  screen  from scratch. If you want a pop-up
  1499.          box that saves the previous image, use Pop and Restore, GetYN
  1500.          or  GetAnyKey  instead, but if you want an empty box, declare
  1501.          some sent[]s as strings of spaces. A range check  error  will
  1502.          occur  if  you  pass  coordinates  that are not legal for the
  1503.          current   video   mode.   For   a   centered  box,  you  must
  1504.          pre-calculate  the  coordinates,  there   is   no   automatic
  1505.          centering.
  1506.  
  1507.          See  Also:  Pop,  Restore.  In  text mode, not use background
  1508.          colors above 7.
  1509.  
  1510.          Example:
  1511.          program test;
  1512.          uses crt,magic;
  1513.          begin
  1514.             makebox(20,10,60,15);
  1515.             repeat until keypressed;
  1516.             XClear;
  1517.             .
  1518.             .
  1519.          end.
  1520.  
  1521.          Performance of Example:
  1522.          An  empty box will appear until a key is pressed. Crt must be
  1523.          in the Uses line because Keypressed is a procedure within the
  1524.          Crt unit (Turbo.tpl).
  1525.  
  1526.          *************************************************************
  1527.          Menu - Procedure                                   Uses Magic
  1528.  
  1529.          Declaration: Menu(x,y : integer)
  1530.  
  1531.          Description:
  1532.              Menu  pops a box on the screen showing lines of text from
  1533.          the array sent[1..18]. One of the lines is highlighted and  a
  1534.          user  can  move  the  highlight  to any of the other items by
  1535.          moving the mouse or pressing the up or down arrow keys.  When
  1536.          the user presses [Enter] or clicks the left mouse button, the
  1537.          currently  highlighted  item number is assigned to the global
  1538.          byte variable mc. The pop-up box disappears and the array  of
  1539.          strings, sent[1..18] is cleared.
  1540.              Two integer parameters are required, the first  indicates
  1541.          the  horizontal  position  of  the  upper left corner and the
  1542.          second is for the vertical position.  If either integer is  a
  1543.          negative  number,   that integer will be ignored and the menu
  1544.          will   be   centered  on  the  screen  in  the  corresponding
  1545.          dimension.
  1546.              Before  calling Menu, a byte variable, mc should be given
  1547.          a value.  Mc is the current MenuChoice,  meaning  the  sent[]
  1548.          corresponding to mc is the one highlighted.  If you state: mc
  1549.          := 1 then the first item on the menu will be highlighted.  If
  1550.          you  forget  to  assign  mc,  a  random  menu  choice will be
  1551.          highlighted with your first call to Menu.
  1552.               When the user presses any non-arrow key or clicks a left
  1553.          mouse button, the pop-up Menu disappears, all sent[]s are set
  1554.          to  '', and U will have a char value corresponding to the key
  1555.          pressed.  If the left mouse button was clicked U will be char
  1556.          #174, and if the right button was pressed, U will be #175.
  1557.              You can then use u or mc to perform operations related to
  1558.          your user's choice. To have the menu return  to  the  screen,
  1559.          sent[]s  must  be  refilled  with your strings and DoubleMenu
  1560.          must be called again. The usual way to use Menu is to put  it
  1561.          into a repeat loop as shown in the example below.
  1562.  
  1563.          Considerations:
  1564.             Maximum sent[]s : 18; Should assign a value to  mc  of  at
  1565.          least   one  and  less than the maximum sent[]. Must reassign
  1566.          text to the sent[]s for subsequent calls to  Menu.  If  in  a
  1567.          graphics mode, you must use DefaultFont (0).
  1568.             In text mode, do not use background colors above 7.
  1569.  
  1570.          See also: sent[], Pop, GetYN, GetAnyKey, DoubleMenu
  1571.  
  1572.          Example:
  1573.          Program Test;
  1574.          uses magic;
  1575.          begin
  1576.             mc := 1;
  1577.             repeat
  1578.                sent[1] := 'Do Thing One';
  1579.                sent[2] := 'Do Thing Two';
  1580.                sent[3] := 'Do Thing tHree';
  1581.                sent[4] := 'Do Thing Four';
  1582.                sent[5] := 'Do Thing fiVe';
  1583.                sent[6] := 'Do Thing Six';
  1584.                sent[7] := '   Quit   ';
  1585.                Menu(-1,-1);
  1586.                if (u = #174) or (u = #13) then
  1587.                case mc of
  1588.                   1 : Procedure1;
  1589.                   2 : Procedure2;
  1590.                   3 : Procedure3;
  1591.                   4 : Procedure4;
  1592.                   5 : Procedure5;
  1593.                   6 : Procedure6;
  1594.                   7 : u := #175;
  1595.                end; {case mc}
  1596.                u := upcase(u);
  1597.                case u of
  1598.                   'O' : Procedure1;
  1599.                   'T' : Procedure2;
  1600.                   'H' : Procedure3;
  1601.                   'F' : Procedure4;
  1602.                   'V' : Procedure5;
  1603.                   'S' : Procedure6;
  1604.                   'Q' : u := #175;
  1605.                  #27: u := #175;
  1606.                end; {case u}
  1607.             until u = #175;
  1608.             CleanUp;
  1609.          end.
  1610.  
  1611.          Performance of example:
  1612.             Mc is set to 1 so when the menu pops up,  the  first  item
  1613.          will  be  highlighted.   Seven sent[]s are given strings. The
  1614.          Menu pops up and the user  presses  a  key  or  operates  the
  1615.          mouse.  Then if U is #174, (because the left mouse button has
  1616.          been pressed) or U is #13, (the  [Enter]  key)  then  a  case
  1617.          statement figures out what to do with the user's menu choice.
  1618.             If mc is between 1 and 6, one of the procedures is called.
  1619.          Of  course,  these procedures can do anything you wish, based
  1620.          upon what menu item the user  has  selected.  The  last  menu
  1621.          choice  (sent[7])  is  'Quit'  and will cause this program to
  1622.          fall through and terminate.
  1623.             U  is  changed  into  an  uppercase  letter  so  that  the
  1624.          following  case  will work whether the user presses a capital
  1625.          or small letter. This second case checks to see  whether  the
  1626.          user  selected  a menu item based upon the capitalized letter
  1627.          hints. You can also  use  function  keys  here.  The  #0  has
  1628.          already  been stripped off, so if you get a ';' then the user
  1629.          pressed [F1] and probably wants 'help.'
  1630.             There is a boolean variable called Functkey which will now
  1631.          be true if the user pressed a function key, such as an  arrow
  1632.          or  [F1]. If the user actually pressed [;] then Functkey will
  1633.          be false. If you want to know what function  key  (or  ALT  +
  1634.          key)  was  pressed,  call the function FunctAscii, which will
  1635.          return the extended ASCII character.
  1636.              Assuming  the user did not select  'Quit'  or  press  #27
  1637.          (the [Escape] key)  or  the  right  mouse  button,  the  menu
  1638.          process will repeat.
  1639.              When  the  user  finally does choose to quit, the CleanUp
  1640.          procedure returns to DOS gracefully.
  1641.  
  1642.          *************************************************************
  1643.          MouseInstalled - Function                          Uses Magic
  1644.  
  1645.          Declaration: (example) if MouseInstalled then
  1646.  
  1647.          Description:
  1648.          This boolean function returns true if a mouse and its  driver
  1649.          are installed.
  1650.  
  1651.          See Also: Poll, SetMouseRows, SetMouseColumns
  1652.  
  1653.          Example:
  1654.          program test;
  1655.          uses video, graph, magic;
  1656.          begin
  1657.             if MouseInstalled = false then sent[1] := 'Mouse not found'
  1658.             else
  1659.             begin
  1660.                BestVideo;
  1661.                sent[1] := 'A mouse is present';
  1662.             end;
  1663.             GetAnyKey(10,10);
  1664.          end.
  1665.  
  1666.          Performance of Example:
  1667.          If  there  is  no mouse then MouseInstalled will be false and
  1668.          'Mouse not found' will pop up in text mode;  If  there  is  a
  1669.          mouse,  then  'A  mouse  is  present' will appear in graphics
  1670.          mode.  When the user presses a key, the program ends.
  1671.  
  1672.          *************************************************************
  1673.          MusicOn - Global Variable                          Uses Magic
  1674.  
  1675.          Declaration: MusicOn := true;
  1676.  
  1677.          Description:
  1678.          This  boolean variable controls whether the sound effects are
  1679.          allowed to play.  The  default  for  MusicOn  is  true.  When
  1680.          MusicOn is set to false, calls to Pink, Twinkle, SoundUp, and
  1681.          SoundDown will be ignored until it is again set to true.
  1682.  
  1683.          Considerations:
  1684.          SPECIAL  NOTE:  The  Turbo.tpl  file supplied by Borland with
  1685.          Turbo Pascal Version 6.0 has a glitch in the  built-in  Delay
  1686.          procedure,  which is used in the generation of sound effects.
  1687.          On machines faster than 30 mhz, Delay does  not  always  work
  1688.          right.   Borland  has  a  free patch for this problem so your
  1689.          animations, sound effects and other uses of Delay  will  work
  1690.          properly   on   all  standard IBM-compatibles.  I have copied
  1691.          the  patch files from Borland's BBS for you and they  are  on
  1692.          this disk. The patch is performed by Delaypat.Bat and to find
  1693.          out  how  to  use  it,  read  Delaypat.DOC.
  1694.              This  Borland read-only BBS is a source of many wonderful
  1695.          bits of source code, and it is all free, except long-distance
  1696.          phone charges. With your modem, dial 1-408-439-9096.
  1697.  
  1698.          See Also: Pink, Twinkle, SoundUp, SoundDown.
  1699.  
  1700.          Example:
  1701.          program test;
  1702.          uses magic;
  1703.          begin
  1704.             sent[1] := 'Do you want sound effects? (Y/N)';
  1705.             GetYN(-1,-1);
  1706.             if u = 'Y' then MusicOn := true else MusicOn := false;
  1707.             twinkle;
  1708.          end.
  1709.  
  1710.          Performance of Example:
  1711.          The user will be asked to press 'Y' or 'N' for sound effects.
  1712.          If the user selects 'Y' then MusicOn will be true and Twinkle
  1713.          will  play.  If  the user selects 'N' then no twinkle will be
  1714.          heard.
  1715.  
  1716.          *************************************************************
  1717.          OutFile - Global Variable                          Uses Magic
  1718.  
  1719.          Declaration: (example) assign(OutFile,'Things.Doc')
  1720.  
  1721.          Description:
  1722.             OutFile is declared globally as a file of type Text. It is
  1723.          used for sending text information from your program  to  disk
  1724.          using the automatic procedures File and FileWriteLn.
  1725.  
  1726.          Considerations:
  1727.             OutFile   is  for  text  only.   Numeric  values  must  be
  1728.          represented as strings for OutFile.   You  can  override  the
  1729.          automatic   use   of   OutFile  with  standard  Turbo  Pascal
  1730.          techniques  such  as  Assign,  ReWrite and Close. As with any
  1731.          output file, make  sure  to  close  OutFile  before  quitting
  1732.          program  if  you  use Turbo Pascal procedures, otherwise data
  1733.          may be lost. All Magic procedures which write to OutFile will
  1734.          automatically close it.
  1735.  
  1736.          See Also:
  1737.          InFile, FileRead, FileReadLn, NameInFile {Magic};
  1738.          Assign,   ReWrite,   ReSet,  Append,  Write,  WriteLn,  Read,
  1739.          ReadLn, Rename, Erase, Close {Borland}
  1740.  
  1741.          Example:
  1742.          Program Test;
  1743.          uses magic;
  1744.          begin
  1745.             NameOutFile('TestFile.Txt');
  1746.             rewrite(OutFile);
  1747.             writeln(OutFile,'This is the only string in the file.');
  1748.             close(OutFile);
  1749.          end.
  1750.  
  1751.          Performance of example:
  1752.              The text file  called  OutFile  within  your  program  is
  1753.          associated  with  'TestFile.Txt'  on  disk. Whether or not it
  1754.          exists, it will be recreated as an empty file  with  ReWrite.
  1755.          Then one line is written to the file and it is closed. If you
  1756.          were to investigate TestFile.Txt with a  word  processor  you
  1757.          would find only one line of text: "This is the only string in
  1758.          the file."
  1759.  
  1760.          *************************************************************
  1761.          NameInFile - Procedure                             Uses Magic
  1762.  
  1763.          Declaration: NameInFile(FileName : string)
  1764.  
  1765.          Description:
  1766.              This procedure automatically closes the present InFile if
  1767.          it is open then renames it to FileName. From this time  until
  1768.          another  call  to  NameInFile,  the  global  string  variable
  1769.          InFile will carry the name passed to NameInFile as FileName.
  1770.  
  1771.          Considerations:
  1772.             If  FileName  is a literal, not a string variable, then it
  1773.          must be enclosed in single quotation marks. FileName must  be
  1774.          DOS-legal  with  up to 8 alphanumeric characters, an optional
  1775.          period, then up to a three  character  extension.  InFile  is
  1776.          used  for  text only and is read-only as used by FileRead and
  1777.          FileReadln.  FileWrite and  FileWriteLn  will  only  work  on
  1778.          OutFile. Full drive designator and pathnames are supported up
  1779.          to 76 characters.
  1780.  
  1781.          See Also:
  1782.          FileWrite, Filewriteln, FileRead, FileReadLn, NameOutFile.
  1783.  
  1784.          Example:
  1785.          Program Test;
  1786.          uses crt,magic;
  1787.          begin
  1788.             NameInFile('TestFile.Txt');
  1789.             answer := FileReadLn;
  1790.             writeln(answer);
  1791.             repeat until keypressed;
  1792.          end.
  1793.  
  1794.          Performance of example:
  1795.              "Testfile.txt" is assigned to InFile. When FileReadLn  is
  1796.          called,   it   looks   to   the  disk  for  the  file  called
  1797.          Testfile.txt and reads one line. This line  is  displayed  on
  1798.          the  screen. The program terminates when the user presses any
  1799.          key. Crt must be in the Uses line  because  Keypressed  is  a
  1800.          procedure within the Crt unit (Turbo.tpl).
  1801.  
  1802.          *************************************************************
  1803.          NameOutFile - Procedure                            Uses Magic
  1804.  
  1805.          Declaration: NameOutFile(FileName : string)
  1806.  
  1807.          Description:
  1808.              This procedure automatically closes the  present  OutFile
  1809.          if  it  is  open  then renames it to FileName. From this time
  1810.          until another call to NameOutFile, the global string variable
  1811.          OutFile will carry the name passed to NameOutFile as FileName.
  1812.  
  1813.          Considerations:
  1814.             If  FileName  is a literal, not a string variable, then it
  1815.          must be enclosed in single quotation marks. FileName must  be
  1816.          DOS-legal  with  up to 8 alphanumeric characters, an optional
  1817.          period, then up to a three character  extension.  OutFile  is
  1818.          used for text only and is write-only as used by FileWrite and
  1819.          FileWriteLn.   FileRead  and  FileReadLn  will  only  work on
  1820.          InFile. Full drive designator and pathnames are supported  up
  1821.          to 76 characters.
  1822.  
  1823.          See Also:
  1824.          FileWrite, Filewriteln, FileRead, FileReadLn, NameInFile.
  1825.  
  1826.          Example:
  1827.          Program Test;
  1828.          uses magic;
  1829.          begin
  1830.             NameOutFile('TestFile.Txt');
  1831.             FileWriteLn('This is a test.');
  1832.          end.
  1833.  
  1834.          Performance of example:
  1835.              Examination with a word processor would reveal that there
  1836.          is a file on the disk called "Testfile.txt" and the last line
  1837.          in  that  file  (and  the  only line if it was a new file) is
  1838.          "This is a test."
  1839.  
  1840.          *************************************************************
  1841.          Number - Function                                  Uses Magic
  1842.  
  1843.          Declaration: (example) i {integer variable} := number
  1844.  
  1845.          Description:
  1846.             This function takes  the  global string variable, Answer,
  1847.          and returns  its  contents  as an integer variable. If there
  1848.          is any  problem,  Problem  (global boolean variable) becomes
  1849.          true and Number will be 0.
  1850.             This is particularly useful after a call to Dialog, which
  1851.          assigns a string to the global string, Answer.
  1852.  
  1853.          Considerations:
  1854.             Must be within the range of an integer as defined by
  1855.          Turbo Pascal.
  1856.  
  1857.          See Also:
  1858.             Dialog, Answer.
  1859.  
  1860.          Example:
  1861.          program test;
  1862.          begin
  1863.             sent[1] := 'How many do you want?';
  1864.             dialog(-1,-1);
  1865.             if number < 40 then do_something else do_different_thing;
  1866.          end.
  1867.  
  1868.          Performance of example:
  1869.             The user is presented with a question to which the answer
  1870.          is typed in the dialog  box.   Number  converts  the  Answer
  1871.          to an integer. In this sample program, if the user  typed  a
  1872.          number  less  than  40   then   the   fictitious   procedure
  1873.          do_something  is  executed,  otherwise do_different_thing is
  1874.          executed.
  1875.  
  1876.          *************************************************************
  1877.          OpenInFile - Procedure                             Uses Magic
  1878.  
  1879.          Declaration: OpenInFile
  1880.  
  1881.          Description:
  1882.              This seldom-used procedure  is  automatically  called  by
  1883.          other  procedures  within  the  Magic unit, but can be called
  1884.          manually too. It Opens and resets the InFile.
  1885.  
  1886.          See Also:
  1887.          FileRead, FileReadLn, NameInFile.
  1888.  
  1889.          Example:
  1890.          Program Test;
  1891.          uses crt, magic;
  1892.          begin
  1893.             NameInFile('Example.Doc');
  1894.             if eof(InFile) then OpenInFile;
  1895.             answer := FileReadLn;
  1896.             write(answer);
  1897.             repeat until keypressed;
  1898.          end.
  1899.  
  1900.          Performance of example:
  1901.             If the last line of the file has been read then  eof  will
  1902.          be  true. Eof is a boolean function returning true if End  Of
  1903.          File  has  been reached. In that case, OpenInFile will reopen
  1904.          the InFile, effectively starting at the beginning. If Eof was
  1905.          true then the line  displayed  on  the  screen  will  be  the
  1906.          first  line  in  Example.doc.  Crt  must  be in the Uses line
  1907.          because  Keypressed  is  a  procedure  within  the  Crt  unit
  1908.          (Turbo.tpl).
  1909.  
  1910.  
  1911.          *************************************************************
  1912.          Pink - Procedure                                   Uses Magic
  1913.  
  1914.          Declaration: Pink
  1915.  
  1916.          Description:
  1917.             Pink  makes  a  sound  typically indicating a key has been
  1918.          pressed or a small action has occurred.
  1919.  
  1920.          Considerations:
  1921.             The boolean Variable MusicOn must be true or Pink will not
  1922.          make  a  sound. The default status of MusicOn is true. It  is
  1923.          possible  that  this  will  not  work as expected on machines
  1924.          faster than 33mhz or  when  multitasking  under  DeskView  or
  1925.          MS-Windows.
  1926.             Must put Crt in uses statement.
  1927.             Make sure to read the special note under MusicOn.
  1928.  
  1929.  
  1930.          See Also:
  1931.          MusicOn, Twinkle, SoundUp, SoundDown {Magic} Sound,  NoSound,
  1932.          Delay {Borland}
  1933.  
  1934.          Example:
  1935.          Program Test;
  1936.          uses crt, magic;
  1937.          begin
  1938.             xclear;
  1939.             repeat
  1940.                u := readkey;
  1941.                pink;
  1942.                write(u);
  1943.             until (u = #27) or (u = #13); {Escape or Enter key}
  1944.          end.
  1945.  
  1946.          Performance of example:
  1947.              The screen will clear. Then every time a key is  pressed,
  1948.          it's  character  will  be  shown on the screen and an audible
  1949.          click  will  be  heard  until the user presses #27, the [Esc]
  1950.          key.  Crt  must  be  in  the  Uses  line because Readkey is a
  1951.          procedure within the Crt unit (Turbo.tpl).
  1952.  
  1953.          *************************************************************
  1954.          PointerOff - Procedure                             Uses Magic
  1955.  
  1956.          Declaration: PointerOff
  1957.  
  1958.          Description:
  1959.             Turns off the mouse pointer or arrow.
  1960.  
  1961.          Considerations:
  1962.              See PointerOn.
  1963.  
  1964.          See Also:
  1965.          Poll, PointerOn, ResetMouse
  1966.  
  1967.          Example:
  1968.          Program Test;
  1969.          uses crt, video, graph, magic;
  1970.          var
  1971.            x,y : word;
  1972.          begin
  1973.             x := 0; y := 0;
  1974.             Bestvideo;
  1975.             PointerOff;
  1976.             repeat
  1977.                poll(px,py,left,right);
  1978.                lineto(px,py);
  1979.                x := x;
  1980.                y := y;
  1981.             until left;
  1982.             resetmouse;
  1983.             pointeron;
  1984.             pointertoxy(x,y);
  1985.             waste;
  1986.             repeat poll(x,y,left,right)
  1987.               until (keypressed) or (left) or (right);
  1988.             CleanUp;
  1989.          end.
  1990.  
  1991.          Performance of example:
  1992.             The  program will switch to a graphics mode and there will
  1993.          be no mouse pointer.  As long as the user moves the mouse,  a
  1994.          trail  of  lines  will  appear  on  the screen. When the user
  1995.          clicks the left mouse button, the mouse pointer will reappear
  1996.          and the drawing of lines will cease. When  the  user  presses
  1997.          any key or mouse button the program will terminate gracefully.
  1998.          Crt  must  be  in  the  Uses   line  because  Keypressed is a
  1999.          procedure within the Crt unit (Turbo.tpl).
  2000.  
  2001.          *************************************************************
  2002.          PointerOn - Procedure                              Uses Magic
  2003.  
  2004.          Declaration: PointerOn
  2005.  
  2006.          Description:
  2007.             Turns on the mouse pointer or arrow.
  2008.  
  2009.          Considerations:
  2010.              Many  mice  require  a  call to ResetMouse before calling
  2011.          PointerON.  You might also want to call PointerToXY to  reset
  2012.          the mouse position to the current position.
  2013.  
  2014.          See Also:
  2015.          Poll, PointerOff, ResetMouse
  2016.  
  2017.          Example:
  2018.          Program Test;
  2019.          uses crt, video, graph, magic;
  2020.          var
  2021.            x,y : word;
  2022.          begin
  2023.             x := 0; y := 0;
  2024.             Bestvideo;
  2025.             PointerOff;
  2026.             repeat
  2027.                poll(px,py,left,right);
  2028.                lineto(px,py);
  2029.                x := px;
  2030.                y := py;
  2031.             until left;
  2032.             resetmouse;
  2033.             pointertoxy(x,y);
  2034.             pointeron;
  2035.             waste;
  2036.             repeat poll(x,y,left,right)
  2037.               until keypressed or left or right;
  2038.             CleanUp;
  2039.          end.
  2040.  
  2041.          Performance of example:
  2042.             The  program will switch to a graphics mode and there will
  2043.          be no mouse pointer.  As long as the user moves the mouse,  a
  2044.          trail  of  lines  will  appear  on  the screen. When the user
  2045.          clicks the left mouse button, the mouse pointer will reappear
  2046.          and the drawing of lines will cease. When  the  user  presses
  2047.          any key or mouse button the program will terminate gracefully.
  2048.          Crt must  be  in  the  Uses  line  because  Keypressed  is  a
  2049.          procedure within the Crt unit (Turbo.tpl).
  2050.  
  2051.          *************************************************************
  2052.          PointerToXY - Procedure                            Uses Magic
  2053.  
  2054.          Declaration: PointerToXY(x,y : word);
  2055.  
  2056.          Description:
  2057.             Moves the mouse pointer to coordinates x and y.
  2058.  
  2059.          Considerations:
  2060.             If  the  pointer  is  turned  off  (PointerOff)  then  the
  2061.          (graphics) CP (Current Position) will be moved to x and y.
  2062.  
  2063.          See Also:
  2064.          Poll, PointerOff, Pointeron, ResetMouse.
  2065.  
  2066.          Example:
  2067.          Program Test;
  2068.          uses crt, graph, video, magic;
  2069.          var
  2070.            x,y : word;
  2071.          begin
  2072.             Bestvideo;
  2073.             x := getmaxx div 2; y := getmaxy div 2;
  2074.             PointerOn;
  2075.             PointerToXY(x,y);
  2076.             repeat until keypressed;
  2077.             CleanUp;
  2078.          end.
  2079.  
  2080.          Performance of example:
  2081.             The  current position is moved to x and y, which have been
  2082.          assigned  the  center  of the screen. The pointer will appear
  2083.          there.  The program waits for  the user to press a key,  then
  2084.          terminates  gracefully.  Crt must be in the Uses line because
  2085.          Keypressed is a procedure within the Crt unit (Turbo.tpl).
  2086.  
  2087.          *************************************************************
  2088.          Pop - Procedure                                    Uses Magic
  2089.  
  2090.          Declaration: Pop(x,y : integer)
  2091.  
  2092.          Description:
  2093.             This  is  the simplest version of a pop-up text box in the
  2094.          Magic kit.  Magic has a pre-declared  array  of  76-character
  2095.          long  strings  called  sent[].  Before  a  call to Pop, these
  2096.          strings are all empty.  You  must  assign  text  to  as  many
  2097.          strings  as  you  wish to display. They must be in order. The
  2098.          first line displayed will be sent[1], the second line will be
  2099.          sent[2], and so on. Any strings after the last one  to  which
  2100.          you have assigned a line of text will be ignored by Pop.
  2101.             Pop  requires  two  integers, x and y. X is the horizontal
  2102.          coordinate  and  y  is  the   vertical   coordinate.    These
  2103.          coordinates  mark  the position on the screen where the upper
  2104.          left corner of the pop up box will occur.  The whole box is 4
  2105.          columns wider than the widest sent[] and two rows taller than
  2106.          the total number of sent[]s which contain text. If you are in
  2107.          text mode the upper left corner of the screen is 1,1 and  the
  2108.          lower  right  corner  is 80,25. In any of the graphics modes,
  2109.          the upper left corner is 0,0 and the lowest right varies.  in
  2110.          CGA,  2-color mode (640 x 200), for instance, the lower right
  2111.          corner is 639,199.
  2112.             In  graphics or text mode, if either x or y are a negative
  2113.          integer, the  box  will  be  automatically  centered  on  the
  2114.          screen in the corresponding dimension.
  2115.             When Pop starts, it first saves the  current  contents  of
  2116.          the screen to memory. Pop will then place its pop-up  box  on
  2117.          the  screen. There is no wait for user input built in.  After
  2118.          a call to Pop, the program will progress immediately  to  the
  2119.          next  step. Therefore, a usual step is to call WaitForUser so
  2120.          the  pop-up  box  will  be seen before the program continues.
  2121.          Then call Restore to get rid of the pop-up  box  and  replace
  2122.          the original screen contents.
  2123.              Actually,   using   Pop   may   be   rare,   since   Pop,
  2124.          WaitForUser and Restore  are  automatically  incorporated  in
  2125.          GetAnyKey, GetYN, Dialog, Menu and DoubleMenu.
  2126.  
  2127.          Considerations:
  2128.             Must  not use x or x integers that are beyond the possible
  2129.          range  for the current video mode. (except negative integers,
  2130.          which will center the pop-up box) It  is  advisable  to  call
  2131.          Restore  some  time soon after done with Pop. Otherwise 4k of
  2132.          RAM is occupied with the saved screen in text mode, and up to
  2133.          around  300k in VGA graphics mode. There can be up to 10 text
  2134.          screens saved at one time when there is sufficient ram space.
  2135.          If an attempt is made to save more screens than possible, for
  2136.          instance, calling Pop 11 times  in  a  row,  only  the  first
  2137.          screen(s) saved will be available for a Restore. If your pro-
  2138.          gram exceeds available RAM space, the IDE will return an  out
  2139.          of memory notice.
  2140.              If in a graphics mode, must use Borland DefaultFont  (#0,
  2141.          bit-mapped).
  2142.              In text mode, do not use background colors above 7.
  2143.  
  2144.          See Also:
  2145.          Restore, GetAnyKey, GetYN, Dialog, Menu, DoubleMenu
  2146.  
  2147.          Example:
  2148.          Program Test;
  2149.          uses magic;
  2150.          begin
  2151.             sent[1] := 'This is a line of text';
  2152.             sent[2] := 'This is another line';
  2153.             sent[3] := 'This line tells the user to press any key';
  2154.             pop(1,1);
  2155.             WaitForUser;
  2156.             Restore;
  2157.          end.
  2158.  
  2159.          Performance of example:
  2160.             Since there are 3 sent[]s a text box will pop up  that  is
  2161.          three lines tall. The third line is the widest, and therefore
  2162.          the  box  will  be  just  large  enough to neatly contain the
  2163.          third, widest line. Pop is given the coordinates of  1,1,  so
  2164.          the  upper  left  corner  of  the  pop  up box will be in the
  2165.          extreme upper left corner of  the  screen.  WaitForUser  will
  2166.          stall  the  program  until the user presses any key or clicks
  2167.          a mouse button. Then Restore restores the screen  as  it  was
  2168.          before  the  pop-up  box  appeared,  which  is  silly in this
  2169.          program, because it ends in the next line.
  2170.  
  2171.          *************************************************************
  2172.          Problem - Global Variable                          Uses Magic
  2173.  
  2174.          Declaration: (example) if problem then
  2175.  
  2176.          Description:
  2177.             Problem is a global boolean variable that is  usually  set
  2178.          to  false  as any graphics or i/o procedure in the Magic unit
  2179.          starts. Then, if a problem occurs, the procedure will  handle
  2180.          the problem as cleanly as possible and set Problem to true.
  2181.             For instance, if FileWrite is asked to write a string to a
  2182.          write-protected disk, the program will not  crash,  but  will
  2183.          not write to the disk, and Problem becomes true. You can then
  2184.          use  Problem  to cause a branch in your program to handle the
  2185.          'problem.'
  2186.  
  2187.          Considerations:
  2188.              Problem must be  checked  before  a  call  to  any  other
  2189.          procedure  in  the Magic unit because the next procedure will
  2190.          reset Problem.
  2191.  
  2192.          Example:
  2193.          Program Test;
  2194.          uses magic;
  2195.          begin
  2196.            NameOutFile('testfile.txt');
  2197.            FileWriteLn('This is a line of nonsense.');
  2198.            if Problem {= true} then
  2199.            begin
  2200.              sent[1] := 'Problem writing to disk';
  2201.              sent[2] := 'Disk may be full or write-protected';
  2202.              sent[3] := 'Press any key to continue..';
  2203.              GetAnyKey(-1,-1);
  2204.            end;
  2205.            .
  2206.            .
  2207.          end.
  2208.  
  2209.          Performance of example:
  2210.             This program tries to write, "This is a line of  nonsense"
  2211.          to   a  disk  file  called  "Testfile.txt."  If  this  proves
  2212.          impossible, then Problem is  true  and  a  three-line  notice
  2213.          pops up on the screen.
  2214.  
  2215.          *************************************************************
  2216.          Px - Global Variable                               Uses Magic
  2217.  
  2218.          Declaration: (example) PutPixel(px,py,white)
  2219.  
  2220.          Description:
  2221.             Px is a global variable defined in  magic.tpu  as  a  word
  2222.          (positive integer). The most common use of px is to designate
  2223.          a horizontal screen position.
  2224.  
  2225.          *************************************************************
  2226.          Py - Global Variable                               Uses Magic
  2227.  
  2228.          Declaration: (example) PutPixel(px,py,white)
  2229.  
  2230.          Description:
  2231.             Py is a global variable defined in  magic.tpu  as  a  word
  2232.          (positive integer). The most common use of py is to designate
  2233.          a vertical screen position.
  2234.  
  2235.          *************************************************************
  2236.          ResetMouse - Procedure                             Uses Magic
  2237.  
  2238.          Declaration: ResetMouse
  2239.  
  2240.          Description:
  2241.             This   restores   the   mouse  situation  to  its  default
  2242.          parameters. The mouse pointer will be relocated to the center
  2243.          of the screen and the left and right mouse button status will
  2244.          be not pressed.
  2245.  
  2246.          Considerations:
  2247.             Some older mice have glitchy mouse  driver  software,  and
  2248.          frequent calls to ResetMouse will not hurt! Call  PointerToXY
  2249.          if  you  want  the  mouse  position  to  be  as it was before
  2250.          ResetMouse.
  2251.  
  2252.          See also:
  2253.          Poll, PointerToXY, PointerOn, PointerOff
  2254.  
  2255.          *************************************************************
  2256.          Restore - Procedure                                Uses Magic
  2257.  
  2258.          Declaration: Restore
  2259.  
  2260.          Description:
  2261.             Restore  replaces the screen contents with a picture saved
  2262.          before a call to Pop. GetAnyKey,  GetYN,  Dialog,  Menu,  and
  2263.          DoubleMenu  call  Restore automatically when they finish, but
  2264.          Pop does not. Restore also frees the memory  which  was  held
  2265.          for the saved screen image.
  2266.  
  2267.          Considerations:
  2268.              In graphics mode, it is easily possible to  exceed avail-
  2269.          able RAM space. Call Restore as soon  as  possible  to  avoid
  2270.          stacking up too many pop- ups.  In VGA, one pop-up may occupy
  2271.          all available  space!  Repeated calls to Restore  brings back
  2272.          the image preceding each Pop. Restore is a  smart  procedure,
  2273.          if called  more  times  than the number of stored screens, it
  2274.          has no effect.
  2275.  
  2276.          See Also
  2277.          Pop, MakeBox.
  2278.  
  2279.          Example;
  2280.          Program Test;
  2281.          uses crt, Magic;
  2282.          begin
  2283.             sent[1] := 'This box is going to';
  2284.             sent[2] := 'be difficult to read';
  2285.             Pop(1,1);
  2286.             delay(1000);
  2287.             sent[1] := 'because this screen';
  2288.             sent[2] := 'is going to cover it up';
  2289.             sent[3] := 'Press any key to get rid';
  2290.             sent[4] := 'of this box';
  2291.             pop(5,2);
  2292.             WaitForUser;
  2293.             Restore;
  2294.             WaitForUser;
  2295.             Restore;
  2296.             delay(1000);
  2297.             CleanUp;
  2298.          end.
  2299.  
  2300.          Performance of example:
  2301.             A box containing two lines of text appears in the  extreme
  2302.          upper  left  corner,  then  one second later, a four-line box
  2303.          partially covers it up.  When the user  presses  a  key,  the
  2304.          second  box  disappears  so  that  the  first one can be seen
  2305.          clearly. When the user presses a key  again,  the  first  box
  2306.          disappears  leaving a blank screen. After a one second delay,
  2307.          the program terminates cleanly. Crt must be in the Uses  line
  2308.          because Delay is a procedure within the Crt unit (Turbo.tpl).
  2309.  
  2310.          *************************************************************
  2311.          Right - Global Variable                            Uses Magic
  2312.  
  2313.          Declaration: (example) if right = false then
  2314.  
  2315.          Description:
  2316.             Right  is  a  global  boolean  variable used to record the
  2317.          status of the left mouse button.  If right =  true  then  the
  2318.          right mouse button has been pressed.
  2319.  
  2320.          Considerations:
  2321.             The  status  of Right will change with every call to Poll,
  2322.          Waste, WasteMouse,  ResetMouse  or  procedures  within  Magic
  2323.          which handle text or pop up boxes.
  2324.  
  2325.          See Also: Poll, Waste, WasteMouse, ResetMouse, left
  2326.  
  2327.          Example:
  2328.          Program Test;
  2329.          uses magic;
  2330.          var
  2331.             x, y : word;
  2332.          begin
  2333.             sent[1] := 'Nothing will change until you click the';
  2334.             sent[2] := 'right mouse button';
  2335.             Pop(-1,-1);
  2336.             WasteMouse;
  2337.             repeat poll(x,y,left,right) until right;
  2338.          end.
  2339.  
  2340.          Performance of example:
  2341.             A box containing two lines of text will stay on the screen
  2342.          until the user clicks the right mouse  button.   The  program
  2343.          will then terminate.
  2344.  
  2345.          *************************************************************
  2346.          SansSerif - Procedure                              Uses Magic
  2347.  
  2348.          Declaration: SansSerif
  2349.  
  2350.          Description:
  2351.              Calling   the   procedure  SansSerif  makes  the  Borland
  2352.          Sansserif font  available  to  graphic-based  programs.  This
  2353.          font will be compiled into the .EXE file.  SANSSERIF.CHR does
  2354.          not have to accompany the finished product.
  2355.  
  2356.          Considerations:
  2357.          Compiled .EXE size increases  by  about  17k. Must add Graph,
  2358.          Video, Fonts, Magic to Uses statement. Do not  use  SansSerif
  2359.          with  Pop,  GetAnyKey,  GetYN, Dialog, Menu or DoubleMenu. To
  2360.          use  SansSerif  font,  type:  SetTextStyle(SansSerifFont,d,x)
  2361.          where  d  represents  direction  (0  is  horizontal),  and  x
  2362.          represents the size of the text, ranging from 1 to 10.
  2363.  
  2364.          See Also:
  2365.          BestVideo,   CGAVideo,  EGAVideo,  VGAVideo,  Small,  Gothic,
  2366.          Triplex {Magic} SetTextStyle {Borland}
  2367.  
  2368.          Example:
  2369.          Program Test;
  2370.          uses crt, graph, video, fonts, magic;
  2371.          begin
  2372.             BestVideo;
  2373.             SansSerif;
  2374.             SetTextStyle(3,0,2); {3 is const: SansSerifFont}
  2375.             outtextxy(100,90,'Test');
  2376.             repeat until keypressed;
  2377.          end.
  2378.  
  2379.          Performance of example:
  2380.             Sansserif font information is compiled into the .EXE file.
  2381.          The   highest   resolution   graphics   mode   is   selected.
  2382.          SansSerifFont is selected for output, then the word 'Test' is
  2383.          written on the screen.  When the  user  presses  a  key,  the
  2384.          program  terminates.  Crt  must  be  in the Uses line because
  2385.          Keypressed is a procedure within the Crt unit (Turbo.tpl).
  2386.  
  2387.          *************************************************************
  2388.          SetMouseColumns - Procedure                        Uses Magic
  2389.  
  2390.          Declaration: SetMouseColumns(max, min : word)
  2391.  
  2392.          Description:
  2393.          You  can  limit  the  travel  of the mouse on the screen with
  2394.          SetMouseColumns and SetMouseRows. SetMouseColumns  needs  two
  2395.          integer  numbers,  the  first  is the maximum column that the
  2396.          mouse is allowed and the second is the minimum column.
  2397.  
  2398.          Considerations:
  2399.             Text mode is usually based on CGA high-res (640 x 200). To
  2400.          work  with a specific text location, divide the mouse x and y
  2401.          coordinates by 8. To place a character in the third column of
  2402.          the second row of the screen (near the upper left corner) you
  2403.          would work at coordinate 16,8.
  2404.             Do not use this procedure unless MouseInstalled.
  2405.  
  2406.          See Also:
  2407.          Poll, PointerToXY, SetMouseRows
  2408.  
  2409.          Example:
  2410.          Program Test;
  2411.          uses video, graph, magic;
  2412.          begin
  2413.             VGAVideo;
  2414.             SetMouseColumns(319,0);
  2415.             SetMouseRows(199,0);
  2416.             PointerOn;
  2417.             repeat poll(px,py,left,right) until left;
  2418.          end.
  2419.  
  2420.          Performance of example:
  2421.             This  example  sets  the  video mode to VGA but allows the
  2422.          mouse to move only within the upper left corner of the screen
  2423.          as if working with the more limited resolution of CGA 4-color
  2424.          mode.
  2425.  
  2426.          *************************************************************
  2427.          SetMouseRows - Procedure                           Uses Magic
  2428.  
  2429.          Declaration: SetMouseRows(max, min : word)
  2430.  
  2431.          Description:
  2432.             See SetMouseColumns, above. SetMouseRows needs two integer
  2433.          numbers, the first is the  maximum  row  that  the  mouse  is
  2434.          allowed and the second is the minimum row.
  2435.  
  2436.          Considerations:
  2437.             Text mode is usually based on CGA high-res (640 x 200). To
  2438.          work with a specific text location, divide the mouse x and  x
  2439.          coordinates by 8. To place a character in the third column of
  2440.          the second row of the screen (near the upper left corner) you
  2441.          would work at coordinate 16,8.
  2442.             Do not use this procedure unless MouseInstalled.
  2443.  
  2444.          See Also:
  2445.          Poll, PointerToXY, SetMouseColumns
  2446.  
  2447.          Example:
  2448.          Program Test;
  2449.          uses video, graph, magic;
  2450.          begin
  2451.             VGAVideo;
  2452.             SetMouseColumns(319,0);
  2453.             SetMouseRows(199,0);
  2454.             PointerOn;
  2455.             repeat poll(px,py,left,right) until left;
  2456.          end.
  2457.  
  2458.          Performance of example:
  2459.             This  example  sets  the  video mode to VGA but allows the
  2460.          mouse to move only within the upper left corner of the screen
  2461.          as if working with the more limited resolution of CGA 4-color
  2462.          mode.
  2463.  
  2464.          *************************************************************
  2465.          Shadow - Global Variable                           Uses Magic
  2466.  
  2467.          Declaration: (example) shadow := color;
  2468.  
  2469.          Description:
  2470.          This sets the color of shadows at the bottom and  right  edge
  2471.          of  pop-up  text boxes, where 'color' is an integer from 0 to
  2472.          15 or a color  constant  as  defined  by  Borland.  Works  in
  2473.          graphics and text mode.
  2474.  
  2475.          Considerations:
  2476.          May  not  have the expected effect when used with the limited
  2477.          palettes of 4-color CGA (mode  0,1  or  2),  2-color  CGA  or
  2478.          Hercules. In text mode, only 8 colors  are  available: 0 - 7,
  2479.          for correct operation (hiding of the cursor).
  2480.  
  2481.          See  also:  MainText,  MainBack,  BoxText,  BoxBack, BarText,
  2482.          BarBack, border.
  2483.  
  2484.          Example:
  2485.          program test;
  2486.          uses magic;
  2487.          begin
  2488.             sent[1] := 'First Thing';
  2489.             sent[2] := 'Second Thing';
  2490.             sent[3] := 'Quit';
  2491.             mc := 1;
  2492.             shadow := Cyan;
  2493.             Menu(-1,-1);
  2494.             .
  2495.             .
  2496.          end.
  2497.  
  2498.          Performance of example:
  2499.             A menu pops up with a LightCyan shadow.
  2500.  
  2501.          *************************************************************
  2502.          Small - Procedure                                  Uses Magic
  2503.  
  2504.          Declaration: Small
  2505.  
  2506.          Description:
  2507.              Calling the procedure Small makes the Borland Small  font
  2508.          available  to  graphic-based  programs.  This  font  will  be
  2509.          compiled into the .EXE file.   SMALL.CHR  does  not  have  to
  2510.          accompany the finished product.
  2511.  
  2512.          Considerations:
  2513.          Compiled .EXE size increases by about 17k.  Must  add  Graph,
  2514.          Video, Fonts, Magic to Uses statement.
  2515.             Do not use Small for Pop, GetAnyKey, GetYN Dialog, Menu or
  2516.          DoubleMenu.
  2517.             To use Small, type: SetTextStyle(SmallFont,d,x) where d is
  2518.          an  integer representing direction (0 is horizontal) and x is
  2519.          an integer from 1 to 10 representing  relative  size  of  the
  2520.          text.
  2521.  
  2522.          See Also:
  2523.          BestVideo,  CGAVideo, EGAVideo, VGAVideo, SansSerif, Triplex,
  2524.          Gothic {Magic} SetTextStyle {Borland}
  2525.  
  2526.          Example:
  2527.          Program Test;
  2528.          uses crt, fonts, video, graph, magic;
  2529.          begin
  2530.             BestVideo;
  2531.             Small;
  2532.             SetTextStyle(SmallFont,0,2);
  2533.             outtextxy(100,90,'Test');
  2534.             repeat until keypressed;
  2535.          end.
  2536.  
  2537.          Performance of example:
  2538.             Small font information is compiled into the .EXE file. The
  2539.          highest  resolution  graphics  mode is selected. SmallFont is
  2540.          selected for output, then the word 'Test' is written  on  the
  2541.          screen.   When  the  user  presses   a   key,   the   program
  2542.          terminates.  Crt  must be in the Uses line because Keypressed
  2543.          is a procedure within the Crt unit (Turbo.tpl).
  2544.  
  2545.  
  2546.          *************************************************************
  2547.          SoundDown - Procedure                              Uses Magic
  2548.  
  2549.          Declaration: SoundDown
  2550.  
  2551.          Description:
  2552.             SoundDown  makes   a  sound  typically indicating a window
  2553.          is being closed or a large action has occurred.
  2554.  
  2555.          Considerations:
  2556.             The boolean Variable MusicOn must  be  true  or  SoundDown
  2557.          will not make a sound. The default status of MusicOn is true.
  2558.          It is possible that this  will  not  work  as  expected  when
  2559.          multitasking under DeskView or MS-Windows.
  2560.             Make sure to read the special note under MusicOn.
  2561.  
  2562.          See Also:
  2563.          MusicOn, Twinkle, SoundUp, Pink {Magic} Sound, NoSound, Delay
  2564.          {Borland}
  2565.  
  2566.          Example:
  2567.          Program Test;
  2568.          uses magic;
  2569.          begin
  2570.             sent[1] := 'Sound effect. Press any key...';
  2571.             SoundUp;
  2572.             GetAnyKey(-1,-1);
  2573.             SoundDown;
  2574.          end.
  2575.  
  2576.          Performance of example:
  2577.              A  SoundUp  sound will occur. a box pops up on the screen
  2578.          with one line of text. When  the  user  presses  any  key,  a
  2579.          SoundDown will occur and the program terminates.
  2580.  
  2581.          *************************************************************
  2582.          SoundUp - Procedure                                Uses Magic
  2583.  
  2584.          Declaration: SoundUp
  2585.  
  2586.          Description:
  2587.             SoundUp  makes  a  sound  typically indicating a window is
  2588.          being opened or a large action has occurred.
  2589.  
  2590.          Considerations:
  2591.             The boolean Variable MusicOn must be true or SoundUp  will
  2592.          not  make  a sound. The default status of MusicOn is true. It
  2593.          is  possible  that  this  will  not  work  as  expected  when
  2594.          multitasking under DeskView or MS-Windows.
  2595.             Make sure to read the special note under MusicOn.
  2596.  
  2597.          See Also:
  2598.          MusicOn, Twinkle, SoundDown,  Pink  {Magic}  Sound,  NoSound,
  2599.          Delay {Borland}
  2600.  
  2601.          Example:
  2602.          Program Test;
  2603.          uses magic;
  2604.          begin
  2605.             sent[1] := 'Sound effect. Press any key...';
  2606.             SoundUp;
  2607.             GetAnyKey(-1,-1);
  2608.             SoundDown;
  2609.          end.
  2610.  
  2611.          Performance of example:
  2612.              A  SoundUp  sound will occur. a box pops up on the screen
  2613.          with one line of text. When  the  user  presses  any  key,  a
  2614.          SoundDown will occur and the program terminates.
  2615.  
  2616.  
  2617.          *************************************************************
  2618.          TextVideo - Procedure                              Uses Magic
  2619.  
  2620.          Declaration: TextVideo
  2621.  
  2622.          Description:
  2623.              This returns a program from a graphics video mode to text
  2624.          mode, the default startup condition. The screen is cleared.
  2625.  
  2626.          Considerations:
  2627.              Any memory held for a saved screen from a pop-up box will
  2628.          be released.  Will  not  work  a  prior  call  to  BestVideo,
  2629.          CGAVideo, HercVideo, EGAVideo, or VGAVideo.
  2630.  
  2631.          See Also:
  2632.          BestVideo, CGAVideo, HercVideo, EGAVideo, VGAVideo.
  2633.  
  2634.          Example:
  2635.          Program Test;
  2636.          uses graph, video, magic;
  2637.          begin
  2638.             BestVideo;
  2639.             sent[1] := 'This is graphics mode';
  2640.             sent[2] := 'Press any key to see text mode';
  2641.             GetAnyKey(-1,-1);
  2642.             TextVideo;
  2643.             sent[1] := 'This is text mode';
  2644.             sent[2] := 'Press any key to quit';
  2645.             GetAnyKey(-1,-1);
  2646.          end.
  2647.  
  2648.          Performance of example:
  2649.             A  box  pops up in the best graphics mode the computer can
  2650.          display. When the user presses a key, the  computer  switches
  2651.          to  text  video  mode  and another box appears until the user
  2652.          presses a key again.
  2653.  
  2654.          *************************************************************
  2655.          Twinkle - Procedure                                Uses Magic
  2656.  
  2657.          Declaration: Twinkle
  2658.  
  2659.          Description:
  2660.             Twinkle makes  a  sound  typically indicating an action
  2661.          has positively been completed.
  2662.  
  2663.          Considerations:
  2664.             The boolean Variable MusicOn must be true or Twinkle  will
  2665.          not  make  a sound. The default status of MusicOn is true. It
  2666.          is  possible  that  this  will  not  work  as  expected  when
  2667.          multitasking under DeskView or MS-Windows.
  2668.             Make sure to read the special note under MusicOn.
  2669.  
  2670.          See Also:
  2671.          MusicOn, SoundUp, SoundDown,  Pink  {Magic}  Sound,  NoSound,
  2672.          Delay {Borland}
  2673.  
  2674.          Example:
  2675.          Program Test;
  2676.          uses magic;
  2677.          begin
  2678.             sent[1] := 'Sound effect. Press any key...';
  2679.             GetAnyKey(-1,-1);
  2680.             Twinkle;
  2681.          end.
  2682.  
  2683.          Performance of example:
  2684.             A box will pop up containing one line of  text.  When  the
  2685.          user  presses  any key, the Twinkle sound will occur and then
  2686.          the program will terminate.
  2687.  
  2688.          *************************************************************
  2689.          Triplex - Procedure                                Uses Magic
  2690.  
  2691.          Declaration: Triplex
  2692.  
  2693.          Description:
  2694.              Calling the procedure Triplex makes the  Borland  Triplex
  2695.          font  available to graphic-based programs.  This font will be
  2696.          compiled into the .EXE file.  TRIPLEX.CHR does  not  have  to
  2697.          accompany the finished product.
  2698.  
  2699.          Considerations:
  2700.          Compiled .EXE size increases by about 17k.  Must  put  Graph,
  2701.          Fonts, Video, and Magic in Uses statement.
  2702.             Do  not  use  Triplex  with Pop, GetAnyKey, GetYN, Dialog,
  2703.          Menu or DoubleMenu.
  2704.             To use Triplex  font  type:  SetTextStyle(TriplexFont,d,x)
  2705.          where  d  is  an  integer  representing  the  direction (0 is
  2706.          horizontal) and x is an integer from 1 to 10 representing the
  2707.          relative size of the text.
  2708.  
  2709.          See Also:
  2710.          BestVideo,  CGAVideo,  EGAVideo,  VGAVideo, SansSerif, Small,
  2711.          Gothic {Magic} SetTextStyle {Borland}
  2712.  
  2713.          Example:
  2714.          Program Test;
  2715.          uses crt, fonts, graph, video, magic;
  2716.          begin
  2717.             BestVideo;
  2718.             Triplex;
  2719.             SetTextStyle(TriplexFont,0,2);
  2720.             outtextxy(100,90,'Test');
  2721.             repeat until keypressed;
  2722.          end.
  2723.  
  2724.          Performance of example:
  2725.             Triplex font information is compiled into the  .EXE  file.
  2726.          The  highest  resolution graphics mode is selected. SmallFont
  2727.          is selected for output, then the word 'Test'  is  written  on
  2728.          the  screen.   When  the  user  presses  a  key,  the program
  2729.          terminates. Crt must be in the Uses line  because  Keypressed
  2730.          is a procedure within the Crt unit (Turbo.tpl).
  2731.  
  2732.          *************************************************************
  2733.          U - Global Variable                                Uses Magic
  2734.  
  2735.          Declaration: example u := readkey
  2736.  
  2737.          Description:
  2738.             U is a general purpose global char  variable  declared  in
  2739.          the  Magic  unit  for internal use, but available for any use
  2740.          within your program.  U originally  stood  for  UserInput.
  2741.  
  2742.          Considerations:
  2743.             U  is  reset by several of the functions and procedures in
  2744.          the Magic Unit.  Do not assume the value of U will remain the
  2745.          same after use of procedures such as Dialog, XReadKey, etc.
  2746.  
  2747.          Example:
  2748.          Program Test;
  2749.          uses magic;
  2750.          begin
  2751.             answer := '';
  2752.             repeat
  2753.                u := upcase(readkey);
  2754.                if ord(u) > 31 then
  2755.                begin
  2756.                   answer := answer + u;
  2757.                   write(u);
  2758.                end;
  2759.             until (u = #27) or (u = #13);
  2760.             .
  2761.             .
  2762.          end.
  2763.  
  2764.          Performance of example:
  2765.             This program is a very stripped down way to get input from
  2766.          the keyboard and change it in to an all uppercase string.
  2767.  
  2768.          *************************************************************
  2769.          VGAVideo - Procedure                               Uses Magic
  2770.  
  2771.          Declaration: VGAVideo
  2772.  
  2773.          Description:
  2774.          This  initializes  the system in VGA graphics mode. VGA video
  2775.          driver will be automatically compiled into the  .EXE  program
  2776.          file, eliminating the need for external EGAVGA.BGI file.
  2777.  
  2778.          Considerations:
  2779.              The resulting .EXE file is much smaller than one compiled
  2780.          after a call to BestVideo.   BestVideo  builds  all  graphics
  2781.          drivers  into  the .EXE file, but VGAVideo builds in only the
  2782.          EGAVGA driver.  This  must  be  called  only  once  during  a
  2783.          program. Video.Tpu must be available until after compilation.
  2784.          Must put Video, Graph, Magic in Uses statement.
  2785.              There   are   several  graphmodes  available for VGA. The
  2786.          default mode for Magic is  640x480  16-color  (GraphMode  2).
  2787.          See the Borland manuals.
  2788.              VGA graphics is memory hungry. It is possible to fill all
  2789.          available RAM with concurrent Pops,  GetYNs,  Menus,  etc. In
  2790.          fact two full screen save can entirely  fill  RAM.  Use small
  2791.          pop-ups or call Restore early and frequently when programming
  2792.          for Vga.
  2793.  
  2794.          See Also:
  2795.          BestVideo,     HercVideo,    CGAVideo,    EGAVido    {Magic};
  2796.          SetGraphMode, Setcolor, etc. {Borland}
  2797.  
  2798.          Example:
  2799.          Program Test;
  2800.          uses crt, video, graph, magic;
  2801.          begin
  2802.             VGAVideo;
  2803.             rectangle(10,10,20,20);
  2804.             repeat until keypressed;
  2805.             CleanUp;
  2806.          end.
  2807.  
  2808.          Performance of example:
  2809.          The  system is put in VGA graphics mode. A small rectangle is
  2810.          displayed in the upper left corner of the  screen  until  any
  2811.          key  is pressed.  The program then terminates gracefully. Crt
  2812.          must be in the Uses line because Keypressed  is  a  procedure
  2813.          within the Crt unit (Turbo.tpl).
  2814.  
  2815.  
  2816.          *************************************************************
  2817.          WaitForUser - Procedure                            Uses Magic
  2818.  
  2819.          Declaration: WaitForUser
  2820.  
  2821.          Description:
  2822.             This  simple  procedure stalls the computer until the user
  2823.          presses a key or clicks a mouse button.
  2824.  
  2825.          See Also:
  2826.          Pop, XReadKey
  2827.  
  2828.          Example:
  2829.          Program Test;
  2830.          uses fonts, graph, video, magic;
  2831.          begin
  2832.             BestVideo;
  2833.             Triplex;
  2834.             SetTextStyle(TriplexFont,3,5);
  2835.             outtextxy(100,90,'Press any key');
  2836.             WaitForUser;
  2837.             CleanUp;
  2838.          end.
  2839.  
  2840.          Performance of example:
  2841.              This program displays the word, "Test" then waits for the
  2842.          user to press a key or click a mouse button.
  2843.  
  2844.          *************************************************************
  2845.          Waste - Procedure                                  Uses Magic
  2846.  
  2847.          Declaration: Waste
  2848.  
  2849.          Description:
  2850.              This  procedure  makes  sure  there  is  nothing  in  the
  2851.          keyboard buffer and if a  mouse  is  installed,  waits  until
  2852.          there  are  no mouse buttons pressed.  U is assigned #126, an
  2853.          uncommon ASCII character.
  2854.  
  2855.          Considerations:
  2856.             WasteMouse is automatically called by Waste.
  2857.  
  2858.          See Also:
  2859.          Pop, XReadKey, WasteMouse
  2860.  
  2861.          Example:
  2862.          Program Test;
  2863.          uses crt, magic;
  2864.          begin
  2865.              writeln('Without Waste, keyboard buffer could cause');
  2866.              writeln('portions of the program to skid past before');
  2867.              writeln('the user knows what is happening');
  2868.              Waste;
  2869.              u := XReadKey;
  2870.              clrscr;
  2871.              writeln('This is a problem when the user holds a key');
  2872.              writeln('down too long');
  2873.              Waste;
  2874.              u := XReadKey;
  2875.              clrscr;
  2876.          end.
  2877.  
  2878.          Performance of example:
  2879.              Three lines appear on the screen. The keyboard buffer  is
  2880.          cleared  out and the program waits until no mouse buttons are
  2881.          pressed.  Then  the  program  waits  for a key to be pressed.
  2882.          Then the screen is cleared and two more lines of text appear.
  2883.          Again,  Waste clears the buffer and waits if a  mouse  button
  2884.          is pressed, and then waits for the user to do something. Then
  2885.          the  screen clears and the program terminates. Crt must be in
  2886.          the Uses statement because clrscr is a procedure  within  the
  2887.          Crt unit (Turbo.tpl).
  2888.  
  2889.          *************************************************************
  2890.          WasteMouse - Procedure                             Uses Magic
  2891.  
  2892.          Declaration: WasteMouse
  2893.  
  2894.          Description:
  2895.              This  simple  procedure  stalls the computer if any mouse
  2896.          buttons are pressed and waits  until  no  mouse  buttons  are
  2897.          pressed.
  2898.  
  2899.          See Also:
  2900.          Waste
  2901.  
  2902.          Example:
  2903.          Program Test;
  2904.          uses magic;
  2905.          var
  2906.             x,y : word;
  2907.          begin
  2908.             sent[1] := 'Click a mouse button to end this program';
  2909.             Pop(-1,-1);
  2910.             WasteMouse;
  2911.             repeat poll(x,y,left,right) until left or right;
  2912.          end.
  2913.  
  2914.          Performance of example:
  2915.              A  sentence appears on the screen until a mouse button is
  2916.          pressed.
  2917.  
  2918.          *************************************************************
  2919.          XClear - Procedure                                 Uses Magic
  2920.  
  2921.          Declaration: XClear
  2922.  
  2923.          Description:
  2924.             Clears  the  screen  and  sets  the  background  color  to
  2925.          MainBack.
  2926.  
  2927.          Considerations:
  2928.             You may not  get  the  effect  expected  when  in  CGA  or
  2929.          Hercules  modes  if  the  selected MainBack color is not  one
  2930.          in the current color palette.
  2931.  
  2932.          See Also:
  2933.          BestVideo,     HercVideo,    CGAVideo,    EGAVido    {Magic};
  2934.          SetGraphMode, Setcolor, etc. {Borland}
  2935.  
  2936.          Example:
  2937.          Program Test;
  2938.          uses crt, video, graph, magic;
  2939.          begin
  2940.             VGAVideo;
  2941.             rectangle(10,10,20,20);
  2942.             sent[1] := 'Press any key...';
  2943.             Pop(30,30);
  2944.             repeat until keypressed;
  2945.             XClear;
  2946.             sent[1] := 'Press any key...';
  2947.             Pop(400,400);
  2948.             waste;
  2949.             repeat until keypressed;
  2950.          end.
  2951.  
  2952.          Performance of example:
  2953.              A small square appears near the upper left corner of  the
  2954.          screen  along with a box with a line of text.  When a  key is
  2955.          pressed, the screen clears and  a box  containing one line of
  2956.          text appears near the lower  right  corner.  When  a  key  is
  2957.          pressed again, the program ends. Crt must be in the Uses line
  2958.          because  Keypressed  is  a  procedure  within  the  Crt  Unit
  2959.          (Turbo.tpl).
  2960.  
  2961.          *************************************************************
  2962.          XReadKey - Function                                Uses Magic
  2963.  
  2964.          Declaration: (example) u := XReadKey
  2965.  
  2966.          Description:
  2967.             Like Turbo Pascal's ReadKey, this returns a  character  as
  2968.          soon  as  a  key is struck. Additionally, XReadKey, returns a
  2969.          character if the mouse is moved or a mouse key is pressed. If
  2970.          the mouse is moved to the right by  8  or  more  pixels,  the
  2971.          character  returned will be #170, and to the left will return
  2972.          #171. Moving the mouse up by 4 or  more  pixels  will  return
  2973.          #173,  and down returns character #172. If the left button is
  2974.          pressed then #174 is returned and the right mouse  button  is
  2975.          #175.
  2976.  
  2977.          Considerations:
  2978.             XReadKey calls Waste before any other action.
  2979.  
  2980.          See Also:
  2981.          XReadLn, Waste {Magic}; ReadKey {Borland}
  2982.  
  2983.          Example:
  2984.          Program Test;
  2985.          uses crt, magic;
  2986.          var i : integer;
  2987.          begin
  2988.             .
  2989.             .
  2990.             repeat
  2991.               u := upcase(XReadKey);
  2992.               if u = #0 then {then it must be a function key}
  2993.               begin
  2994.                  u := readkey; {no need for XReadKey here}
  2995.                  if u = 'H' then u := #173;  {up arrow}
  2996.                  if u = 'P' then u := #172;  {down arrow}
  2997.               end;
  2998.               case u of
  2999.                 #172 : inc(i);
  3000.                 #173 : dec(i);
  3001.                  'Z' : do_something_else;
  3002.               end; {case}
  3003.             until (u = #27) or (u = #175); {[Esc] or right button}
  3004.             .
  3005.             .
  3006.          end.
  3007.  
  3008.          Performance of example:
  3009.             Computer waits for user input. If user moves the mouse  up
  3010.          (#173)  or  down (#174) or presses the up or down arrow keys,
  3011.          then the variable i is incremented  or  decremented.  If  the
  3012.          user  presses 'z' or 'Z' then do_something_else (an imaginary
  3013.          procedure) is called.  Z can be upper  or  lowercase  because
  3014.          when  XReadKey  is  assigned  to U it is first converted to
  3015.          uppercase by Upcase {Borland}. This repeats  until  the  user
  3016.          presses  the [Esc] key (#27) or clicks the right mouse button
  3017.          (#175). Because there is a  call  to  the  Borland  procedure
  3018.          Readkey,  Crt must be in the Uses line (readkey is in the Crt
  3019.          unit  (Turbo.tpl),  but XReadKey itself would not require Crt
  3020.          in the uses line  because  Magic.tpu  automatically  accesses
  3021.          Crt.
  3022.  
  3023.          *************************************************************
  3024.          XReadLn - Function                                 Uses Magic
  3025.  
  3026.          Declaration: (example) Tempstring := XReadLn(x,y,HowLong)
  3027.  
  3028.          Description:
  3029.             You  will  find  this very useful in database applications
  3030.          where the user has to  fill  in  blanks  in  a  form.  Unlike
  3031.          Borland's  Readln  procedure  this  allows  you  to limit the
  3032.          length of a string the user can type.
  3033.             This is similar to Turbo  Pascal's  Gotoxy  combined  with
  3034.          readln.  XReadLn  need three integer variables. The first two
  3035.          are  the  x  and   y   screen   coordinates of the upper left
  3036.          corner of the place where the user's input will be displayed.
  3037.          X is the horizontal position and y is the vertical.  In  text
  3038.          video mode the upper left corner of the screen is 1,1 and the
  3039.          lower  right  corner  is  80,25.  In graphics modes the upper
  3040.          left corner is 0,0 and the lower right varies.   In  the  CGA
  3041.          320x200  mode,  for instance, the lower right corner would be
  3042.          319,199.
  3043.             The  last  number required, HowLong, is an integer for the
  3044.          number of characters you will allow in the string.   Example:
  3045.          if  you  have  a  form in which the user is to type a 4-digit
  3046.          number in a space, you call XReadLn with the x and y position
  3047.          of the start of the space, then 4, to limit the length of the
  3048.          number the user may enter to 4 digits. When the user  presses
  3049.          [Esc]  or  [Enter]  or  clicks  a  mouse  button,  XReadLn is
  3050.          finished.
  3051.  
  3052.          Considerations:
  3053.             XReadKey  calls  Waste  before  any  other action. Maximum
  3054.          string length is 76 characters. This procedure uses XReadKey,
  3055.          so  with  wise  programming  you  can  answer  function   key
  3056.          responses and mouse actions within the typing of a string.
  3057.             This function is useful  for  reading  from  the  keyboard
  3058.          only, not for reading files.
  3059.             Always  set  textcolor  and  textbackground before calling
  3060.          XReadLn, because otherwise, it will  use  the  most  recently
  3061.          assigned colors, which might  be  shadow and border, (default
  3062.          black and black!) after a pop-up box.
  3063.             No automatic centering is available.  Negative coordinates
  3064.          will have unpredictable results - probably a crash!
  3065.  
  3066.          See Also:
  3067.          XReadLn, Waste {Magic}; Readln, Textcolor, Textbackground
  3068.           {Borland}
  3069.  
  3070.          Example:
  3071.          Program Test;
  3072.          uses crt,magic;
  3073.          var
  3074.             namestring : string;
  3075.          begin
  3076.             gotoxy(1,10); write('What is your name?');
  3077.             textcolor(white); textbackground(blue);
  3078.             namestring := xreadln(20,10,40);
  3079.          end.
  3080.  
  3081.          Performance of example:
  3082.             At  1,10,  "What  is your name?" appears on the screen. At
  3083.          the end of this  line  a  cursor  appears  and  the  user  is
  3084.          expected to type a  name.  The  user's text will be white and
  3085.          the  background  color  will  be  blue.  The user cannot type
  3086.          beyond 40 characters.  When the user presses [Enter] or [Esc]
  3087.          or  clicks  a  mouse button, the program ends. Crt must be in
  3088.          the Uses line because GotoXY is a procedure  within  the  Crt
  3089.          unit (Turbo.tpl).
  3090.  
  3091.          *************************************************************
  3092.  
  3093.                      ADVANTAGES OF HAVING THE SOURCE CODE:
  3094.  
  3095.          *  With  the  easy-to-understand  source  code,  you can make
  3096.          modifications to customize it exactly to your needs.
  3097.  
  3098.          * You can learn many 'secret' or hard to find   Turbo  Pascal
  3099.          programming techniques.
  3100.  
  3101.          *  Even  though  Magic.tpu  takes little room and runs  quite
  3102.          fast,  and  even  though  Turbo Pascal is very smart and only
  3103.          builds code that is actually called in to .EXE files, you can
  3104.          strip down Magic.Tpu for even greater efficiency.
  3105.  
  3106.          * You can use portions of the source code as  a  frame  work,
  3107.          changing  this  or  that, inserting your own stuff, and build
  3108.          amazing programs of your own invention.
  3109.  
  3110.          * You can look at  my  approach  to  programming  and  laugh,
  3111.          possibly  commenting  under  your  breath about how you would
  3112.          have done it better.  Then, with  the  source  code  in  your
  3113.          possession, you can do it better!
  3114.  
  3115.          Notice: This is shareware. Feel free to copy  and  distribute
  3116.          without  modification.   If  you use any portion of the Magic
  3117.          Unit in your programs then registration is a legal necessity.
  3118.          Send  $29.95  to  Another Company.  Complete, well-documented
  3119.          easy-to-understand source code is available. For registration
  3120.          + registration, send $59.90.
  3121.  
  3122.          Send US funds drawn on a US bank to:
  3123.  
  3124.                                 Another Company
  3125.                                  P.O. Box 298
  3126.                               Applegate, OR 97530
  3127.                                       USA
  3128.                                  503-846-7884
  3129.  
  3130.  
  3131.          Even though this seems quite bug-free to me,  it  is  version
  3132.          1.0  and  you may find a surprise or two. I make no warranty.
  3133.          Thanks for trying this software.  Please feel free to  submit
  3134.          bug reports, which I will turn into fixes in later versions.
  3135.  
  3136.                                                            - Jeff -
  3137.                                                        October 28, 1991
  3138.  
  3139.          P.S.
  3140.          If  you require technical assistance, you can try to phone me
  3141.          at 503-846-7884. Best bet is 9-5 weekdays, but I'm not always
  3142.          available.
  3143.  
  3144.          P.S. #2
  3145.          Since you are going to write  some  wonderful  programs,  you
  3146.          might as well start making money with them! You won't have to
  3147.          work  in  an  office doing programming for someone else.  You
  3148.          can write exactly the kind of programs you want to write, and
  3149.          make money at home!
  3150.              The  'secret'  is shareware.  Does it work?  You bet! You
  3151.          can easily have a small success, making some  extra  spending
  3152.          money  each month, or with some practice, you can have a wild
  3153.          success, and make a fine living! There are some  millionaires
  3154.          who   make   their   ever-growing  fortune  entirely  through
  3155.          shareware.
  3156.              ANOTHER  COMPANY  shows  you everything.  Besides our own
  3157.          shareware  successes,  including  WRITER'S   DREAM,   BICYCLE
  3158.          TUNE-UP  AND  REPAIR,  MONEY,  BLACKBOARD,  BETTER  EYESIGHT,
  3159.          WHAT'S  IN  THAT  BOX?  and  THE UNIVERSAL CONVERTER, we have
  3160.          researched the shareware market, we  have  interviewed  other
  3161.          shareware  authors  and  have  learned about all sides of the
  3162.          rapidly expanding shareware business.
  3163.               We show you how  to  write  programs  that  capture  the
  3164.          public's   interest,   how   to   make  sure  your  customers
  3165.          'register', and how to get money by other means through  your
  3166.          shareware.  We  show  you  more. We show you frequency charts
  3167.          indicating which  types  of  programs  sell  best,  we  offer
  3168.          suggestions  for  programs as yet unwritten,  we  talk  about
  3169.          your  on-disk  instruction  manuals,  we even show you how to
  3170.          write user-friendliness into your programs.
  3171.               Can  you  succeed without  SUCCESS WITH SHAREWARE?  Yes!
  3172.          But  why do  it  the  hard  way?  We  have  learned  all  the
  3173.          super-professional   approaches,   the   pitfalls   and   the
  3174.          shortcuts. We'll tell you all about it, and then  instead  of
  3175.          stumbling  around  for  the  first couple of years, you'll be
  3176.          a professional from the start!
  3177.              To get your copy of SUCCESS WITH SHAREWARE! (which is not
  3178.          shareware, itself - only  available  from  Another  Company),
  3179.          send $19.95. Please specify if you need 3.5" disk size.
  3180.  
  3181.                                                          Thanks,
  3182.                                                      - Jeff Napier -
  3183.                                                      January 9, 1992
  3184.  
  3185.          You can order products by writing your order on plain  paper,
  3186.          or  by  printing the included ASCII file called Order.frm, or
  3187.          by phoning 1-503-846-7884, generally weekdays between  9  and
  3188.          5, west coast time.
  3189.